This section explains how to customize the display of OpenSearch search results.  Customization is required to brand the default search results page with organizational metadata. Customization is also required to allow searching between different collections.

On this page:

• Default Search Result User Interface Generation
• Human Resources Required for Search Result Customization
• Customization Procedures
• Custom Sample Web Application Components
• Installing the Sample Web Application
• XSL Style Sheet Customizations

Default Search Result User Interface Generation

An example of the default search result user interface can be seen at http://archive-it.org/public/search.html?host=&query=torture&partner=369&hitsPerDup=1&cid=746256. The user interface is generated by transforming the XML response from the OpenSearch server into HTML using an XSL style sheet. For more information on XML and XSL, visit http://www.w3.org/XML/ and http://www.w3.org/TR/xslt respectively.  The XML output from the OpenSearch server for the search http://archive-it.org/search-master/opensearch?q=energy&i=867  is shown below.

The process of converting the XML response into HTML is shown below.  Third party developers (partners) wishing to customize the search result page are responsible for building the Custom Web Application displayed in the diagram.

Human Resources Required for Search Result Customization

Programming resources with knowledge of XML, XSL, and a Web computer language are required to create a customized search result page.

Customization Procedures

To build a customized search result page, the XSL style sheet that generates the HTML user interface must be modified.  Also, a custom Web application must be built to query the OpenSearch server and apply the style sheet to the server's XML response.  The custom Web application can take many forms.  Examples include Java servlets, PHP pages, and Ruby on Rails components.  Each type of Web application has benefits and drawbacks.  Consult a programming resource for more information.

The customization procedure can be broken down into the following sub-procedures.

• Download the default XSL style sheet.
• Build the custom Web application

Downloading the Default XSL Style Sheet

1. Open a Web browser and go to https://github.com/aaronbinns/tnh
2. Click on the "Downloads" button
3. Choose the appropriate type of archive to download
4. Inflate (open) the archive on your local machine
5. The XSL style sheet is located at:  src/web/search.xsl

Building the Custom Web Application

The custom Web application has two responsibilities:

1. Query the OpenSearch server hosted by Archive-It
2. Format the XML results from the OpenSearch server into HTML using a customized version of the search.xsl style sheet

To illustrate the implementation of these responsibilities, a sample Web application is provided.  It can be downloaded here.  The sample Web application is a Java servlet but its structure can inform the creation of Web applications in any language.

Custom Sample Web Application Components

Installing the Sample Web Application

The sample Web application (test-app.war) can run in any Java servlet container.  The recommended servlet container is Tomcat 6.0.  Tomcat 6.0 can be downloaded here.  Install Tomcat 6.0 and copy the test-app.war file into the Tomcat webapps directory.  Start Tomcat and navigate to the following URL: http://localhost:8080/test-app/SearchResultGenerator.  The page that displays should look like the image below.

For Tomcat installation and management information, see http://tomcat.apache.org/tomcat-6.0-doc/index.html.

XSL Style Sheet Customizations

This section describes various customizations to the search.xsl style sheet.

Customizing the Headers and Title

The default title and headers are shown in the image below.

The default title is defined by the XML.

The default headers are defined under the comment, "Page header: title and search form," in search.xsl.  The XML snippet below displays the default headers.

To change the headers, modify the lines, "Archival Search Sample XSLT" and "This simple XSLT demonstrates the transformation of OpenSearch XML results into a fully-functional, human-friendly HTML search page.  No JSP needed.."  To change the title modify the XML: <title>Search for <xsl:value-of select="title" /></title>    An example customization is shown below.

Modified Title

Modified Headers

The resulting search page is shown below.  

Adding Collection Choices to the Search Page

By default, the search functionality queries ALL collections, even collections that have been defined by other partners.  Make the following customization to allow the user to limit the searchable collections to those defined by a specific partner.  An example is provided to illustrate this procedure.

If a partner has two collections with the ids 100 and 200, it would be useful to define two check boxes to limit the search to these two collections.  

NOTE: To find the collection ids of a partner's collections, see: Find your collection's ID number.

An example of a search page with collection check boxes is shown below.

Modifying the search.xsl style sheet to display collection check boxes involves adding the following lines of XML.

This XML code above defines two check boxes that, when selected, will pass the values 100 and/or 200 to the custom Web application, which will format the search query by using these values as the i parameter.

NOTE:  The collection ids and the collection names must be HARDCODED in the custom XML.  At this time, there is no way to dynamically retrieve the collection ids and collection names of a specific partner.  If the collection name is changed or a new collection is added through the Archive-It user interface, the XML displayed above must be modified to reflect the changes.  Synchronization is a manual procedure.

Place the custom XML code directly below the following line in the search.xsl style sheet.

Remember to change the three values of the following elements in the custom code to reflect your collection information.