Building structSearch and structBrowse Resultset Templates

From TechWiki

Introduction

structSearch and structBrowse conStruct modules are used to display a series of results coming from the Search structWSF web service endpoint. These two Drupal modules generally use a generic resultset display to display the results from the endpoint.

However, there is a way to template these results. The selection of the template to use to display the results depends on the dataset provenance of the record to template.

Note that this templating mechanism is different from the one used to template records' page using structView.

Location of the Template Files

The structSearch and structBrowse template files are simple PHP files. These files are located in:

• conStruct/modules/structBrowse/display.php
• conStruct/modules/structSearch/display.php

Simple Execution Workflow

What we call a structSearch or a structBrowse "template" is in fact a sub-section of the display.php file. The display.php files are respectively called by the structSearch.module or a structBrowse.module files.

Each time a record is being processed to be displayed, the display.php script get executed. This means that each time display.php get executed, it is to display a single record within the entire resultset that is getting displayed to the user.

Record's Structure

The display.php script has access to the $result variable. This variable is an array structure that describe the record to be displayed. All the information about that record is available in this structure. The display.php script only has to select the information it wants to display in the search, or browse, resultset.

The array structure of the $result variable is quite simple:

$result = array("dataset" => "http://...",
                "type" => array(
                                 "type-1" => "",
                                 "type-2" => ""
                               ),
                "http://predicate-1" => array(
                                               array(
                                                      "text" => "",
                                                      "uri"  => ""
                                                    ),
                                               array(
                                                      "text" => "",
                                                      "uri"  => ""
                                                    )
                                              ),
                "http://predicate-2" => array(
                                               array(
                                                      "text" => "",
                                                      "uri"  => ""
                                                    ),
                                               array(
                                                      "text" => "",
                                                      "uri"  => ""
                                                    )
                                              ));

Anatomy Of display.php

Template Selection

What we call a "template" for structSearch and structBrowse is nothing more than a case: statement in the display.php script.

The a template is selected depending on the provenance of the record to display. The provenance of a record is the dataset where it is indexed. You have the possibility to create one "template" per dataset hosted on the instance. Note that you could easily create "sub-templates" for each type of records that is indexed in a given dataset.

If no "template" is defined for a given dataset, then the default "template" will be used to display information about the record. Here is main "template" selection structure for a display.php file:

 
  switch ($result["dataset"])
  {
    case "http://test.com/dataset/1/":
      // ...
    break;
    case "http://test.com/dataset/2/":
      // ...
    break;
    case "http://test.com/dataset/3/":
      // ...
    break;
    default:
      // ...
    break;
  }

Template Creation

Once a new section, for the dataset you want to handle has been added to this list, you have to start the creation of the template. What the template will do is to iterate over the target record's attribute/values, and to generate the HTML code to inject into the resultset. The code can embed JavaScript code or even Flash embedded widgets.

All the code produced by the template has to be appended to the $preview variable. It is the content of that variable that will be displayed to the user.

Let's take a look at the following template which displays information about documents describing interviews:

  case "http://test.com/dataset/interviews/":
 
    $preview = "<table width=\"100%\" style=\"border-top:0; border-bottom:0;\">";
 
    $abstract = "";
    $interviewee = "";
    $interviewer = "";
 
    foreach($result as $property => $value)
    {
      // Skip these properties. We don't have anything 
      // to display related to them.
      if($property == "dataset" || $property == "type")
      {
        continue;                
      }        
 
      switch($property)
      {
        case Namespaces::$bibo."abstract":
          foreach($value as $text)
          {
            $abstract = $text["text"];
          }
        break;
 
	case Namespaces::$foo."#interviewee":
          foreach($value as $text)
          {
            $interviewee = $text["text"];
	  }
	break;
 
	case Namespaces::$foo."#interviewer":
          foreach($value as $text)
          {
            $interviewer = $text["text"];
	  }
	break;
      }
    }
 
    // If there is an abstract, we display it in the body
    // of the result, within the resultset, displayed to
    // the reader.
    if($abstract != "")
    {
      $preview .= "<tr><td style=\"vertical-align: top; text-align:left;\">";
      $preview .= $abstract."<br/><br/>";
 
      // Let's add the information about the interviewee and the
      // interviewer of that interview document.  
      if($interviewee != "")
      {
        $preview .= "<em>Interviewee: $interviewee</em><br/>";
      }
 
      if($interviewer != "")
      {
        $preview .= "<em>Interviewer: $interviewer</em>";
      }
 
      $preview .= "</td></tr>";
    }  
 
 
    $preview .= "</table>";    
  break;

This is how structBrowse and structSearch resultsets templates have to be created. In the worse case, the default: template will be used.