Introduction

SearchMonkey provides us with two ways to modify a user's search results using extracted data. One is to create enhanced results, where we control the appearance of the search result. The other is to create an infobar, which provides general information about a particular site.

In this example we'll show how to create enhanced results, based on metadata that we've made available to SearchMonkey. After you've completed this tutorial you will have an application that can be used to modify Yahoo! search results so that they look like this:

Note how the enhanced search results are mixed in with other search results that are formatted in the ordinary way. And also note how the enhanced results include not only information about specific vacancies, such as location, but also links to pages that are commonly used by job applicants.

If you want to try the sample application, enable DEFRA enhanced results in Yahoo! Search, and then search for something like "administrative assistant Carmarthen".

Creating a new presentation application

Navigate to the SearchMonkey page at http://developer.yahoo.com/searchmonkey/.

Click on the button labelled "Build an app", and you'll be asked to log in if you aren't already. If you don't have a Yahoo! ID; then you'll need to create one, but that only takes a minute or two. Once you have registered and logged in, you'll see the SearchMonkey dashboard:

From the dashboard you can create a number of different types of application, but the one that we are interested in is a presentation application; click Create a New Application and you'll see a screen like this:

Enter a name (such as "DEFRA vacancies enhanced results") and a description (such as "An enhanced results application that contains details of DEFRA job vacancies."), and then accept the terms of service, before clicking Next Step.

Indicating which pages to match against

The next step is to tell SearchMonkey which URLs you want to process, when they occur in search results, which involves a URL pattern, rather than a specific list of URLs. To illustrate how to work out what your URL pattern is, we'll use DEFRA.

DEFRA has a number of vacancies listed in a common folder:

http://www.defra.gov.uk/corporate/recruit/vacancies/rcre1013.htm
http://www.defra.gov.uk/corporate/recruit/vacancies/rcre1017.htm
http://www.defra.gov.uk/corporate/recruit/vacancies/rcre1022.htm
http://www.defra.gov.uk/corporate/recruit/vacancies/rcre1028.htm
http://www.defra.gov.uk/corporate/recruit/vacancies/rcre1054.htm

Each of these jobs has a common part of the URL, which is:

http://www.defra.gov.uk/corporate/recruit/vacancies/

The 'trigger' URL pattern is created by placing a wildcard on the end of this base URL, as follows:

http://www.defra.gov.uk/corporate/recruit/vacancies/*

Add the trigger URL that is appropriate for your information, and click on Autofind URLs. This instructs the tool to try to find some URLs for you to test with, but if no suitable matches are found you can enter some into the list below. We'll enter all five of the DEFRA jobs listed above so that it gives us as much data as possible to test with:

Click on Save & Refresh, and at the bottom of the page the preview area should display the selected URLs exactly how they would appear in a normal Yahoo! search:

If you want to check that the URLs you are using are correct then step through the preview list by clicking the right arrow. Once you are happy with the URLs you have chosen, click on Next Step. Your display should now look something like this:

Choosing which data services will provide metadata

Now that SearchMonkey knows which search results we'd like to modify, we need to tell it how we'd like those results modified. We do this by replacing the normal search result display with one that we make up ourselves, using relevant metadata.

The first thing we need to do is bring in the metadata specific to the vacancies, so click on Add More Data Services. A dialog-box will pop up asking you to choose from the data services you have available:

Select whichever ones you want to use, and you'll see them added to the list:

You're now ready to format the output, so click on Next Step.

Formatting the enhanced results

SearchMonkey is now showing us a form into which we can place instructions about how to display each of these pieces of metadata:

Replace the text in the data entry field with the following:

public static function getOutput() {
    $ret = array();

    $ret['title'] = "Job vacancy at " . Data::get('smid:wk6/rel:Employer/vcard:fn') . ": " . Data::get('smid:wk6/rel:Listing/dc:title');

    // Image
    $ret['image']['src'] = Data::get('smid:wk6/rel:Employer/rel:Thumbnail/@resource');
    $ret['image']['alt'] = "";
    $ret['image']['title'] = "";
    $ret['image']['allowResize'] = true;

    // Deep links - up to 4
    $ret['links'][0]['text'] = "All vacancies";
    $ret['links'][0]['href'] = "http://www.defra.gov.uk/corporate/recruit/vacancy.htm#vacancies";
    $ret['links'][1]['text'] = "Salary and Benefits";
    $ret['links'][1]['href'] = "http://www.defra.gov.uk/corporate/recruit/vacancy.htm#salary";
    $ret['links'][2]['text'] = "Equality commitment";
    $ret['links'][2]['href'] = "http://www.defra.gov.uk/corporate/recruit/vacancy.htm#equality";
    $ret['links'][3]['text'] = "Home page";
    $ret['links'][3]['href'] = Data::get('smid:wk6/rel:Employer/vcard:url/@resource');

    // Key Value pairs - up to 4
    $ret['dict'][0]['key'] = "Location";
    $ret['dict'][0]['value'] = Data::get('smid:wk6/rel:Listing/geo:location');
    $ret['dict'][1]['key'] = "Salary";
    $ret['dict'][1]['value'] = "£" . Data::get('smid:wk6/rel:Listing/job:salaryFrom') .
      "-" . "£" . Data::get('smid:wk6/rel:Listing/job:salaryTo');
    $ret['dict'][2]['key'] = "Reference";
    $ret['dict'][2]['value'] = Data::get('smid:wk6/rel:Listing/dc:identifier');
    $ret['dict'][3]['key'] = "Closing date";
    $ret['dict'][3]['value'] = Data::get('smid:wk6/rel:Listing/v:closingDate');

    return $ret;
}

Click on Save & Refresh and the preview area at the bottom should change to something like this:

Once you are happy with the layout, click Next Step to save your application:

Testing your presentation application

To see you application in action, click on Try. Your search preferences will be loaded, with your new application indicated as of type 'To be Added':

Click on Save and you will then be given a choice of whether to go back to the developer tool, or to try your application in Yahoo! Search; choose the latter option, and you'll be presented with the normal Yahoo! Search page.

Enter some text from one of the vacancies you have been dealing with, such as "administrative assistant Carmarthen". The results of your search should look something like this:

Note how the enhanced search results are mixed in with other search results that are formatted in the ordinary way. And also note how the enhanced results include not only information about specific vacancies, such as location, but also links to pages that are commonly used by job applicants.

Sharing your presentation application

Finally, if you want to make it easy for users to 'install' your enhanced results application, then you can provide a link to a page with a preview of your application, and a button that lets user include it in their search configuration.

If you go back to the previous page, you'll see that below the Try option is Make:

Click this and a page will be presented which in turn provides a link to the Yahoo! Search Gallery page, with your application displaying.

In the case of the example we've been working on here, this page is:

http://gallery.search.yahoo.com/application?smid=TAq.s

You can add this to your web-page by adding mark-up like the following:

<a href="http://gallery.search.yahoo.com/application?smid=TAq.s">View DEFRA vacancies as enhanced results in Yahoo! Search</a>