Recipes to extend onCue

add links to internet searches and services

This recipe allows you to link to an existing Internet search page. The recipe below will not work with every search service - some require a login, for example; others use incompatible methods. These more complex pages may need Qbits written in Java. However, the good news is that we have found that most web search engines can be accessed from onCue with this simple recipe - in fact, most of the ones you see in onCue are!

step 1 - choose the web page

Let's say you want to link to the search at:

http://www.hcibook.com/hcibook/search.html

This page is a simple but typical search engine front page. It has a text entry area and a button marked 'search'.

This is only the beginning, however. When you enter some search words and click 'search', 'find' or 'go' at a search web site, the text you have entered is sent back to the web site for processing. In order to do this automatically from onCue you need to find out what is sent back to the search engine.

step 2 - show the current URL in the web browser

Do you normally see the current page URL at the top of your web browser (called 'Address' in Microsoft Internet Explorer and 'Location' in Netscape Navigator)?

If not, turn this feature on:

Netscape: View > Show > Location Toolbar

Internet Explorer: View > Toolbars > Address Bar

(The exact form may vary from browser to browser.) Now you can see where your browser is going.

step 3 - do a search using the search engine

Enter some easily identifiable search text, for example 'XXXX YYY'. If the search requires a specific format (e.g. ZIP code), then choose any identifiable valid text.

Now press 'search' (or whatever the site search button is called).

step 4 - find the search URL using the web browser

Wait for the search results to come back and then look at the URL at the top of the page. The hcibook.com search has the following URL:

        http://www.hcibook.com/hcibook/search/dosearch.cgi?query=XXXX+YYY

Typically it will have a question mark (?) somewhere in it and one or more name=value pairs separated by ampersands (&). One of these should have your search text as the 'value' part. In the example above 'query=XXXX+YYY '.

Notice that the space has become a '+' (and possibly other special characters have been changed). This is something the browser does so that your text doesn't get confused with other parts of the URL when it is sent. The search engine knows this and turns these back into spaces, etc. onCue will do a similar expansion for you when it makes a search URL to send to a browser.

Copy this URL and put into a text editor (e.g. Notepad).

If the URL doesn't seem to have your text in it (and they are sometimes quite long), look at 'another way to find a search URL' below.

step 5- generalise the search URL

You can now edit the URL in your text editor. Find your search text and replace it with '$0'. In the example this would be:

    http://www.hcibook.com/hcibook/search/dosearch.cgi?query=$0

The '$0' is the marker that onCue will use to know where to put the search text from the clipboard. Now the URL you have is not about your specific search text, but is generalised ready for any text!

step 6 - encode special characters in the URL

Because the URL is going to be embedded into an XML file, some characters have to be 'escaped' so as not to confuse the XML. You need to change all & characters to &amp;, all < to &lt;, all > to &gt; and all $ (except the one in $0) to $$.

    &    ->    &
    <    ->    &lt;
    >    ->    &gt;
    $    ->    $$

The hcibook URL doesn't need any translation, but it is common to find & characters in search URLs. For example, if the URL was:

 
   http://www.somesite.com/complexsearch.cgi?query=$0&option=fast

you would change it to:

    http://www.somesite.com/complexsearch.cgi?query=$0&option=fast

step 7 - choose an icon

You will need to find a GIF or JPEG image (just as used in a web site) to appear as an icon in the onCue window when your keywords are selected. The size of icon needed is 32x32 pixels. Other-sized images will be scaled to fit the space, but it is better to do this beforehand if you can.

Remember that this icon is what you will see in the onCue window - make it something memorable!

Is there some image or part of an image on the site that you can use? Perhaps you can design your own with a web image creation program such as Macromedia Fireworks, Xara Webster or one of the shareware tools. Use the colours and style of the site if they are distinctive. Alternatively look for relevant clip-art on the web.

The eye on hcibook.com is quite distinctive. We've already made it into an icon that you can use in this example. Right-click on the image and choose Save image as... or Save picture as... from the drop-down menu. Save the image somewhere on your hard disk, but not in the aQtive folder at this stage. Name the file eye-icon.gif

step 8 - describe your Qbit

You need to think up a name and various descriptions of your Qbit for onCue to use for tooltips, etc.

Unless you understand XML and its conventions, do not use any special characters such as <>=" in your descriptions.

qbitname

the name you would like to call your qbit - this is used in several places, including the name at the top of the tooltip and the onCue Qbit preferences. You will also need this name when you get to adding your XML Qbit to onCue later.
example: HCI Book Search

help

Some useful help text for anyone using your Qbit. This will appear as the second line of the tooltip associated with your icon in onCue and as the tooltip for your icon in the onCue Qbit preferences.
example: Search for references to this topic in the HCI book

label

A few words to appear in the dropdown menu from your icon in onCue.
example: search the HCI book

step 9 - make the XML file

Open a search-template page. Select the text in your browser window and copy it into a text editor. Notepad (in the Windows Start>Programs>Accessories menu) is ideal.

Edit the file ...

• replace **qbitname** with your Qbit's name
• replace **keywords** with your keyword list separated by commas, and with no quotes
• replace **icon** with the name of your icon file.
• replace **yourname** with your own name
• replace **help** with your help text for anyone using your Qbit.
• replace **label** with your Qbit label.
• replace **webpage** with the generalised search URL (the one with $0 in it).

Ignore the rest of the XML!

Save the file as something like hcibook.xml

It should look like this search-example page

step 10 - put your XML Qbit into onCue

Follow the instructions in adding your XML Qbit to onCue.

step 11 - try it out

Restart onCue, then try copying some words, such as "web design".

You should see your icon appear. If you are connected to the Internet double-click on it to select HCI book search from the menu - and you are there.

congratulations!

You have made a custom Qbit!

It will even be there as an icon in the onCue preferences box.

if things go wrong ...

See my XML doesn't work.

Note: If you later want to edit the Qbit specification, open it by launching Notepad, or your preferred text editor, and choosing Open from the File menu, rather than by double-clicking on hcibook.xml. When you see the 'open' dialogue box select 'All files' in the 'Files of Type' section and then browse down to myqbits.xml.

another way to find a search URL

If you couldn't get the right URL to work at step 4, there are several possible reasons:

• The search engine uses the "HTTP POST method" - this means the information is not sent as part of the URL, but separately. (To verify this, you can view the page source of the original search page to see if the FORM has the attribute METHOD=POST.) Unfortunately this version of onCue XML Qbits does not support the POST method, but we will do so in future versions. Remember to register as a developer to be kept informed of updates and new versions.

• The search engine relies on cookies or other means to trace sessions and refuses to serve you if you haven't followed its own route through its site. Again, there is nothing you can do about this in this version of onCue XML Qbits.

• The search engine goes through one or more stages of redirection so that the URL you see is not the original one sent by the search page. You can do something about this, but you do need to be reasonably proficient at HTML. Go to the original search page (the one where you type text, not the result page). Look in the source for the FORM tag that includes the search text box. Using the ACTION attribute of the FORM tag and the various input fields (including hidden fields), try to reconstruct the URL the FORM will return when the submit button is pressed.

fine tuning - other built-in types

Look at the XML template file and notice the line:

<For Name="com.aqtive.qbits.general.SomeWords" Type="Java Class">

This says that the search engine accepts 'some words' - that is between 1 and 15 words. You don't want to send a whole paragraph to a search engine!

For different searches you may want different kinds of data. You can produce sophisticated recognisers of your own (see have an aQtive Intranet! for one example), but onCue comes with a set of pre-defined recognisers that you can use yourself. This list is changing all the time so keep an eye on the aQtive developers pages.

Try changing the Name tag to read one of the following:

• com.aqtive.qbits.general.Word - a single word
• com.aqtive.qbits.general.Words - any number of words
• com.aqtive.qbits.web.PotentialURL - a URL
• com.aqtive.qbits.example.Name - a person's name
• com.aqtive.qbits.web.EmailAddress - an email address
• com.aqtive.qbits.address.ZipCode - US zip code
• com.aqtive.qbits.address.PostCode - UK post code

Note that, just as with the built-in services of onCue, all of these are 'approximate' recognisers. They recognise things that appear to be an email address, name, etc., but they can get it wrong. However, the user will know, so if you are about to run a search engine that requires a post code to work, it is sensible to make this clear in the tool tip/help text - e.g. "look up Post Code in Flo's fish and chip shop finder".

More recipes to extend onCue

• go to specific web pages on given keywords
• add links to Internet searches and services
• aQtivate your own web site with onCue
• have an aQtive Intranet!