12pm - 1pm
Eat a hearty lunch and clear your mind. :)
1pm - 1:30pm
Assess your existing collection search capabilities
OpenSearch is, at the end of the day, search, so it needs to run on top of an existing search implementation. Key points to discover:
- What parameters are accepted? Just keyword, or others?
- Can you support "paging" if there are many results?
- What data do you get back from the search?
- You need, at minimum, a title and a link, but you'll really be happier if you also have a short description and a thumbnail. (and eventually more metadata would be ideal)
- What format is it in?
- If you're using a Google Search Appliance, it's already XML and you're halfway there.
- Is it coming out as HTML through a template? (Can you format it like this? That's the HTML version of OpenSearch)
- ... basically you need to find a way to grab the search data and transform it into a format that OpenSearch supports (ideally RSS for optimal compatibility)
1:30pm - 2pm
Look at examples
These are examples of various results for OpenSearch queries. I think this is more useful to start with than the spec (which we'll get to shortly).
And here are a few examples of the OpenSearch description document:
Leave those examples open in another window and move on...
2pm - 2:30
Read over the spec
Not the whole thing, since for this first round I would really just copy what you need from the examples above. Just skim it and use it to clarify how to modify the examples.
- How to format your description doc which announces a) that you're doing OpenSearch and b) what options you support.
- How to format the response doc:
2:30pm - 4:30pm
Get right to it
Results XML:
- If you have the ability to output your search results in a brand new template, I'd start from scratch and make it look like the simplest format possible (see examples above).
- This is an XML file, so we have to announce it properly: make sure to set the Content-Type header to text/xml for this page.
- If you're using a Google Search Appliance, I'd check out these links:
- If you're tied to a third-party CMS, you might be in a bit of a bind.
- Drupal users have two modules to look at, but none yet working for Drupal 7:
- Anyone else have a CMS success story to share? Try googling the product name and opensearch, it may be built in.
- If it's truly a locked box but you have working web search results, you may be able to build an XSLT stylesheet to transform the results into a standard format:
- ... I've decided this is a bit out of scope for the afternoon project how-to guide. If you know what the above line means and feel like you can do it, carry on! (and document it here!)
Description file:
- This can be a static (hand-coded) file for now. Just make sure it includes the required elements and an example search that's guaranteed to have results (for testing)
- Again, make sure this file comes back from the server as type text/xml
Discovery link:
- (obviously only do this once it's working!)
- The search pages on your site need to refer to the OpenSearch description. This looks like this:
- <link rel="search" type="application/opensearchdescription+xml" href="http://www.powerhousemuseum.com/collection/database/opensearch/opensearch_desc.xml" title="Museum collection search" />
4:30pm - 5pm
Test and iterate
- See if your XML validates here: http://validator.w3.org/
- Extra bonus, see if it validates as RSS: http://validator.w3.org/feed/
- Don't panic -- while testing now, it looks like only the Powerhouse actually validates, ours have a few errors. Still usable.
- Try to add more metadata.
- See the examples above for dcterms examples and MediaRSS. Those two seem to be the most immediately useful, but if you're up for it you should try to map into CDWAlite!
5pm
Go get a beer and brainstorm next steps
Ideas for use:
- Extend the Powerhouse's wordpress plugin to pull from a generic OpenSearch search instead of their API.
- This is a great use-case because it applies to anything your bloggers might use, but could also extend to making a plugin for MS Word to allow curators to import collection data easily.
- Advertise your OpenSearch capabilities in the comments so others can integrate your collection in their results
- See Fair Use of Thumbnail Images for any concerns about this
- Also look for an exciting example of cross-site search coming this summer from (where else) the Netherlands.
- Check out Cool stuff made with cultural heritage APIs for more ideas
- Play with Yahoo Pipes to mash up your collection with Geo data, wikipedia, etc
- Use your feed to easily submit your images to a developer who would love to try to process them and return color information.
- Let someone harvest your data to build a tour app.
- ... what else?
Done. Who's first?