Displaying search result list

Displaying a search result list is a quite complex method. The data is going through the following steps, before it could be shown in the user's screen:

1. The XC search module implements hook_search(). When Drupal search, XC shows a distinct tab on the search result list, labeled "Search XC results". The user should click on this tab to get the XC search result.
2. DT calls the xc_search_do_search($query) function, where $query is simply the value of the hook_search's $key parameter, i.e. the query string. Since the URL path contains the query itself, we use URL parameters to modify the properties of the searches. These parameters are:
   • filter The filter queries, which help us to reduce the result set to a subset. The filter queries are used by Solr. We use filters for example when clicking a facet item. More about this feature, please consult the Solr wiki page. If you want to use multiple filters, just use the filter[] notation, like filter[]=filter1&filter[]filter[]=filter2. Each filter should be in Licene query format: key:value.
   • start The first result in the list. Default is 0.
   • rows The number of rows in each search result list. Default is the current value of XC_SEARCH_LIMIT constant, which is 10 at the time of writing.
   • page The page number of the search result list to display. Default is 0.
   • debug If you set it to 1, it prints out to some debug information to the screen.
   • search_type A key for some predefined search settings. Currently we have 3 search types defined:
     • standard The standard query. It prevents search in work, expression, holdings, and item level records inside XC schema. This is the default query.
     • mlt More like this query
     • browse The search use by the browse pages. It allows you to display up to 100 000 records in a page.
3. Pass parameters to Solr, and receive results.
4. Calls show_item_array($solr_document, $highlight_snippets, $hit_counter, $debug_mode);. This function prepares and result the data in a Drupal Search API compatible format, which is an array (see the key at hook_search()). Since the API make it possible to augment the array with custom fields under the 'extra' key, we fill the following fields:
   • xc_record This is a representation of the metadata schema as an array. You can use the schema field names as key in the array, eg. $xc_record['dc:title'] will contain the Dublin Core title element in a DC record. Since we use not just those fields, which are in a given records, but 'computed fields', we add some special keys to this array. These are:
     • full_display_url The URL of the full display. This is very important variable, use this to link search result items to nodes.
     • count_holdings The number of holding records belongs to this manifestation.
     • remote_xml_link Link to the original OAI-PMH record.
     • local_xml_link Link to the locally generated XML record.
     • solr_link Link to Solr document (for debugging purpose)
     • sibling_link Link to sibling documents (having same work or expression record)
     • full_display_link Link to full display of the node.
     • syndetics_ids See later.
     • image_url See later.

     You can use these variables in templates, but the most of these are useful in a debugging context.

   • element Element is a derivative of the metadata record. You can merge different fields together, or select one of them to create 'display template elements'. You can do that in its administrative interface. It is usefull to make the templating more easy. Example: you have the following fields: director, artist, writer, director of photography, and you create a new field, called 'contributor', which covers all these fields, and in the template you shouldn't list all types of contributors every time, just the only contributor field. The DT package contains the following predefined elements for manifestations: creator, contributor, citation, language, publisher, abstract, format, title
   • counter Counter in human readble form, i.e. it starts from 1, and not 0.
   • syndetics_ids An array of bibliographical identifiers (ISBN, OCLC number), can be used by Syndetics module
   • image_url If we know the URL of a cover image belonging to this record, we put it here. We know it only if we have find it out previously, and stored in a cache - so at this point DT won't compute, or request an API to get the URL, just use cached values if any.
   • node_id The node id
   • highlight The highlight string which contains the keyword in context, as you set it on the XC Search module highlight settings admin page.
   • ncip_item_ids This is an associated array of NCIP provider IDs, and bibliographical identifiers. With this information we could ask for circulation statuses and other NCIP related information.
5. If the array of search results is fullfilled, the Search API calls the hook_search_page($results);. In our implementation we call the xc_search_search_results theme, which displays the result list.
6. theme_xc_search_search_results($results) is the function we use to display search result. The page contains
   1. the search results itself in a table -- the rows of the table is themable, since it calls the xc_search_result_list_row theme (see it below)
   2. some Ajax methods, which adds more information to the page, currently: cover images, and circ status information
   3. checkboxes, and a function bar, with which you can select/deselect items, and run different operations on the selected elements
   4. the standard navigation bar

   The xc_search_result_list_row theme now contains a row with four columns.

   • The first column contains a counter, and a checkbox. The checkbox's value is compound the node id, and the record id. Please do not change the value, not even the 'name' attribute of the checkbox, because otherwise the JavaScript functions won't work.
   • The second column is a placeholder for a thumbnail image. Its ID is 'coverart-' + node id, and its class is node id. The same warning is also relevant: do not change this, unless you should change the xc_search.module and the javascript file as well (xc_search.js).
   • The third column is a placeholder for the bulk of the data. We use the $result['title'] here, which comes from the Search API's result array title key, what we created with this theming: 'title' => theme('xc_search_metadata', $xc_record, $element, 'title', $counter); .
     We haven't mentioned, that xc_search_metadata is a special theme. In the administrator interface you can define templates for each metadata format. You should select a type of template, now from this set: title, snippet, full_display. Title is used for displaying titles, snippet is use for displaying other, but not all fields, and full is used for displaying all fields of the record. For the shake of performance, when you store a template in the admin interface, it will we flushed out to the file system, as [metadata format] + '_' + [template type] + '.tpl.php' inside sites/all/modules/xc/xc_search/templates directory. Inside those templates you can use the following variables:
     • $base_url Drupal's global $base_url
     • $id The record's identifier
     • $xc_record The metadata record (same as $xc_record elsewhere)
     • $element The array of display template elements mentioned above

     We can say, that while the xc_search_result_list_row is a skeleton which is good for any type of formats, the templates used with xc_search_metadata contains format specific contents.

   • The forth column contains the highlighed contexts, its class is highlight.