Tuesday, June 12, 2012

adding Open Graph Protocol metadata to XTF subject search results

Postscript:  After encountering some technical problems with the use of Facebook on the database site, I've removed all but the site-level OGP data.  The example code functions.  

Description of problem

I'm using Open Graph Protocol metadata to enhance user engagement with the Naval Reactors History Database. I've coded the top-level site with OGP metadata, which is a very straightforward process. The XTF platform is used to support discovery for this database. OGP metadata is simply embedded in the HTML markup for the main form, as defined in the XTF file searchForms.xsl. The outputted metadata makes the site's search page an object in the Facebook social graph and enables users to express a Like relationship with the site.

I am also interested in embedding OGP structured metadata into topical pages within the NRHDB site, which is a much more challenging task. In short, I want to display OGP metadata for some subjects prominently covered in the database, using the database's controlled vocabulary to identify each subject.

Solution

The key XTF file for this task is resultFormatter.xsl and I used both XTF's debug mode support and the Facebook Linter in implementing this functionality.

Here's a rough outline of the steps that I performed for one specific topical search:

1. Identify the simplest URL that can be used to pull up a subject search (example: http://navalreactorshistorydb.info:8080/xtf/search?f1-subject=S1W).

2. Open this URL in XTF's debug mode, step 4.

3. Save the raw XML results for the search to local disk; this is the XML that is fed to the resultFormatter.xsl stylesheet.

4. Analyze the XML structure, particularly the data returned under the /crossQuery/parameters/param elements. This will be used to guide the creation of the XPath expressions used in step 6.

5. Open resultFormatter.xsl and add a local parameter.


6. Add the following code, immediately after the head section's title element. This XSLT code performs a test on the XML data to determine, first, if it's a controlled vocabulary search and, second, if it's a search for the specific term. If both conditions are met, OGP metadata for the topic is inserted into the HTML output displayed on the results screen.


The OGP documentation should be consulted on structuring this metadata and for other rules, such as thumbnail size requirements.

The results can be viewed using the Facebook Linter. I'm still exploring how to best implement subsite or topical page OGP metadata for the Naval Reactors History Database and welcome any comments on this approach and procedure.

----

Addendum

This excerpt provides another example - adding the Open Graph metadata only when viewing the first set or screen of results. This requires the addition of another local parameter (countInfo, mapped to /crossQueryResult/query) and a second xsl:if statement.



Thus far, with some of the major subjects coded in the resultsFormatter.xsl file, performance doesn't seem to be a problem, in terms of the time to display the results screen.