November 17, 2008

Build your own site specific search engine with BOSS

We've written a lot about BOSS here before, but somehow I thought there's a quick example missing how you can use it to build a full custom search box on your server.

Seeing that I had trouble to access search results of this blog on the Blackberry (not our blog's fault, but the browser it comes with), I had a go and created a much easier interface to searching this blog. Here's a quick how-to explaining the steps to the interface.

Check out the example

First of all, check out the result of the whole exercise. Following are some screenshots with explanations:

The search result display with unexpanded keywords

The search result display with expanded keywords

The search result display with previous and next links

Download the example

You can download the whole solution, ready for uploading to your server. The code is heavily commented so we won't go through it here line by line here.

Requirements

The example as it is requires you to get an own application ID for boss and have a server with PHP, the simpleXML and curl extensions (most PHP5 servers will have this).

Configuring your search

In order to change the search to your needs, open the boss-search-config.php file and change the settings to your needs. You have to add your application ID and you can change all the labels and messages in this file:

// insert your app id here, get it at https://developer.yahoo.com/wsregapp/
$appID = '';
// filename to point back to the search result page (keywords and pagination)
$filename = 'index.php';
// urls to restrict the search to 
$sites = 'developer.yahoo.net/blog';
// messages to display 
$noresultsmessage = 'No results found.';
$resultsmessage = 'Showing $start to $end of $all results';
$badtermmessage = 'Illegal search term, please only use words and spaces';
// labels 
$keywordslabel = 'Keywords:';
$nextlabel = 'next';
$previouslabel = 'previous';

Code explanation - HTML

If you open index.php in your editor you will see that all you need to do make the search work is to provide a form and add two includes where you want the results to appear:

  
<form action="index.php" method="get" accept-charset="utf-8">
<p><label for="s">Search for:</label>
<input type="text" id="s" name="s"><input type="submit" value="Search"></p>
</form>
<?php include_once('./boss-search-config.php'); ?>
<?php include_once('./boss-search.php'); ?>
  

In the rest of the HTML you can go wild styling your search. All the look and feel is defined in searchstyles.css

Code explanation - PHP

For detailed step-by-step information open the boss-search.php file in your editor and check the comments. In essence all the script does is check the url parameters, sanitize them and assemble a call to the BOSS API using curl. There's not much clever magic to it and the result sets of BOSS having nextpage and previouspage urls makes it very easy to create pagination.

The API call to BOSS uses the so far undocumented view=keyterms parameter which gives you keywords related to the search result page. In this example we are using these to allow for detailed filtering - users can click the keywords to drill down deeper in the search.

Code explanation - JavaScript

Technically there is no real need to add any JavaScript to make this search work, but I thought it would be nice if the keywords are not visible all the time but can be hidden and shown if the user wants it.

The JavaScript uses YUI3 and is explained in the comments of boss-search.js. In essence what it does is add a class called js to the element with the ID results. You can use this in the CSS to hide all the nested UL elements.

The script then turns all the "keywords" labels into links and shows and hides the nested lists by applying or removing a class called show to them. The paragraph containing the "keywords" labels get a class called open when the keywords are shown. All of this makes it possible for you to fully style the experience.

I hope this can help you get started in building your own search engines for yourself or clients.

Chris Heilmann
Yahoo Developer Network

Posted at November 17, 2008 4:01 PM | Permalink

Bookmark this on Delicious

Comments

Posted by: Pat Cote at January 1, 2009 7:59 AM