A common use for browser toolbars is to make it easy to search for some information and get the results directly in the main browser window. All the main search engines have such toolbars, usually created using C++ and distributed via standard installers. But using the formsPlayer soft-bar library, we can create handy browser extensions for Internet Explorer using barely a few lines of XForms. To illustrate, we'll create a toolbar that uses the recently published API documentation for the popular Prototype Javascript Framework.
How the documentation is stored
The documentation is pretty straightforward. The page for the Element object is:
http://prototypejs.org/api/element
whilst the page for the Form object is:
http://prototypejs.org/api/form
Methods and properties on an object are also available directly, for example, the method Element.addClassName is available at:
http://prototypejs.org/api/element/addclassname
An XForm to access the documentation
A simple form to access this information need be no more than one control and an action handler, so we'll begin with an input control to collect the topic of interest to the user:
<body>
<xf:input ref="topic">
<xf:label>Topic:</xf:label>
</xf:input>
<body>
This control allows the user to enter a search term, which is then stored in a node called topic. Once the user has entered a topic to search for we want to use the value in topic as part of the URL, just as we illustrated above. We need to make one small change though, and that is we'd like a user entering element.addclassname to be taken to:
http://prototypejs.org/api/element/addclassname
To achieve this, we'll replace any periods with '/', and then add the result to the end of the basic URL for the documentation. The XPath for this is simply:
concat('http://prototypejs.org/api/', translate(topic, '.', '/'))
Now we know how to work out the URL we want, how do we make use of it?
The load action
XForms provides an action handler called load that will navigate to a URL, just like <a> in HTML. load is much more powerful though, since the URL is not limited to being a string of text; it can be created from other data that is available in the XForms model. But more than that, since the navigation is tied to an action handler and not a piece of the user interface--as the anchor tag is in HTML--the features that load provides can be used in a much wider range of situations.
An example of using load with just a straightforward string literal for the URL might be:
<xf:load resource="http://prototypejs.org/api/element" />
A typical use might be to create a trigger that navigates to a page, in just the same way that <a> does; the following are in fact directly equivalent:
<xf:trigger appearance="minimal"> <xf:label>element</xf:label> <xf:load ev:event="DOMActivate" resource="http://prototypejs.org/api/element" /> </xf:trigger> <a href="http://prototypejs.org/api/element">element</>
There is no equivalent in HTML for the more advanced type of navigation, where the URL is created from data in the XForms model, although the following probably conveys the point:
<xf:trigger appearance="minimal"> <xf:label>View topic</xf:label> <xf:load ev:event="DOMActivate"> <xf:resource value="concat('http://prototypejs.org/api/', topic)" /> </xf:load> </xf:trigger> <a href="http://prototypejs.org/api/{topic}">View topic</>
Using DOMActivate with an input
Now that we know how to use load, we need to link it to the data entered into the input control. We could just use the trigger that we created above to illustrate the use of load, but we actually don't need to, since pressing [ENTER] in an input control will generate its own DOMActivate event. We therefore only need to add our action handler to the input control--with a minor modification to our XPath statement to take into account that topic is now our evaluation context--and we are able to perform everything we have just discussed:
<body>
<xf:input ref="topic">
<xf:label>Topic:</xf:label>
<xf:load ev:event="DOMActivate">
<xf:resource value="concat('http://prototypejs.org/api/', translate(., '.', '/'))" />
</xf:load>
</xf:input>
<body>
This is our complete form, and in just a few lines of XForms we are able to take a value from our users, and when they press [ENTER], use that value to navigate to a page within the Prototype API documentation. Now we need to turn this form into a toolbar.
Running the form in a toolbar
As this simple form stands, if the user entered a topic to look for, and then pressed [ENTER], the form would be replaced with the correct page from the Prototype documentation. Whilst this is not ideal behaviour when the form is running in the main browser window, it's just what we want when the form is running as a soft-bar. This is because any navigation that takes place in the soft-bar--whether it's a toolbar, side-bar, footer-bar or explorer-bar--is 'bounced' through to the main window. As a result, it's very quick and easy to create toolbars such as this one, that search Google, Flickr, IMDB, Wikipedia, and so on, and show the results in the main window.
To complete turning our form into a toolbar, we need to indicate its title as it will appear in the toolbar:
<head>
<title>Prototype API Documentation Search</title>
<meta name="dc:creator" content="Mark Birbeck" />
and set the toolbar's starting, maximum and minimum dimensions:
<meta name="dc:creator" content="Mark Birbeck" />
<meta name="maxwidth" content="300" />
<meta name="maxheight" content="21" />
<meta name="minwidth" content="300" />
<meta name="minheight" content="21" />
<meta name="defwidth" content="300" />
<meta name="defheight" content="21" />
<style type="text/css">
Installing the toolbar
Installation is extremely straightforward, and follows the same pattern described in HOWTO: Creating a del.icio.us side-bar and installer. If you want to install the toolbar you can do so from here. (You'll need formsPlayer, but this form will install it automatically.) Also, if you'd like to get the code and use it to create your own toolbars, it is available from here.