AnnotateUrl

Try It Out

If you want to check out the AnnotateUrl plugin, do the following:

How to setup the plugin:
- Start WBI and setup your browser to use WBI as a proxy.
- Register the AnnotateUrl plugin on the WBI console by typing (on one line):
  register com/ibm/wbi/examples
  /annotateUrl/annotateUrl.regAlternatively you can register it using the Graphical User Interface.
- Check to see whether the plugin is registered and enabled. Go to the WBI Setup page. The AnnotateUrl plugin should be listed in the table with a checkmark next to its name. If the plugin is not listed, try registering it again. If the checkmark is not there, click on the box to the left of the plugin name. If you are using the GUI, open the plugins folder in the left pane, click on the AnnotateUrl plugin and check the right pane. If the plugin loaded correctly it is "loaded and enabled".
- Open another browser window. Use that window to try out the plugin, and use this window to display the documentation. (To open another window using Microsoft Internet Explorer, go to File -> New -> Window. To open a window using Netscape Navigator, go to File -> New -> Navigator Window.)
How to use the plugin:
- Go to the setup page _annotateUrl/setup and enter a number of urls or parts of urls in the form. Choose a color for each of them. You can skip this step and use the three urls that are set up for demo purposes already. These urls are: www.ibm.com, www.almaden.ibm.com and ibm.com.
- Visit a few Web sites in the ibm.com domain. You'll notice that most links on these pages have colored backgrounds. The backgrounds indicate where in IBM these links lead.

What It Does

When browsing a Web site you sometimes would like to know if a link will lead you out of that site. Alternatively you would like to know when any Web site you visit links to your site or company. This is not always obvious from the link anchor or context. The AnnotateUrl plugin provides an easy way to monitor links on Web pages for a couple of domains or url parts you specify. So if you want to see which links lead to .gov sites, or which links in a publication list lead to .pdf files, you can now have all these links color coded.

How It Works

Architecture

The AnnotateUrl plugin consists of two main parts. The first of these provides an interface to the plugin, so you can setup which urls you would like to mark and with what color. The other part is the actual plug-in. It consists of two DocumentEditors. One of them inserts a stylesheet into the page and the other one modifies links on the page to use one of the defined styles if there is a match.

The setup part consists of two generators. The first generator creates a Web form so you can enter urls you are interested in and pick colors for these urls. The second generator interprets the form data submitted, adjusts the plug-in settings, makes sure these changes are written to the persistent store and then creates a result page reflecting your input.

Implementation Details

The SetupGenerator creates the setup form. The rule to configure this generator is

(host=%null% | host~_annotateUrl) & path=/setup

The first part makes sure we are using WBI as a proxy (otherwise we would have a domain name in there). To access the setup page we go to the page _annotateUrl/setup. The resulting form is populated with the current settings of the plugin. The html of the form is first constructed in a variable. The SetupGenerator then creates a StaticHtmlGenerator with this variable and forwards the RequestEvent to this generator to send the form to the browser. When the user clicks the Submit button in the form, the data is submitted to the url

_setupResult

This translates to a url: _annotateUrl/_setupResult and is processed by
The SetupResultGenerator has the rule

(host=%null% | host~_annotateUrl) & path=/_setupResult

It receives the results from the submitted form. The generator first extracts the form data, sets internal variables and writes the new settings into the persistent store. Then it creates a simple result page reflecting the new settings (again using a StaticHtmlGenerator).
The Stylesheet is added to every page the plugin processes, including the result page from the SetupResultGenerator. If you look at the code of that generator you'll notice that we do not use styles to color the links, yet the resulting page definitely contains colored links. The reason is that also this page is processed by MyLinkAnnotator (see below). This has to do with the sequence in which generators and editors process requests. Generators run before all editors. This means that the output from the SetupResultGenerator gets processed by MyLinkAnnotator, like any other Web page. Therefore the links in that page are color coded as well.
MyLinkAnnotator is a LinkAnnotationEditor and although it is relatively short in code lines, it does the actual work in this plugin. Like all LinkAnnotationEditors it overrides the editLink method. It first extracts the url of the link from the LinkInfo object. If the url matches any of the partial urls defined by the user it has to modify the link (otherwise it doesn't have to do anything). We use the color of the first match we find. This allows a more specific match to override a more general one if it is earlier in our list.

If this link has to be modified, the MyLinkAnnotator gets the entire link (the html) from the LinkInfo object, splices in some code to make the link display using a specific style and sets the html for the link to this modified code.

Some key WBI classes that were used:

Package com.ibm.wbi.protocol.http.beans

StaticHtmlGenerator Used by both setup generators to sent the setup form and the setup result page to the browser.

AddPreambleEditor Used to add the stylesheets to the top of all pages.

LinkAnnotatonEditor Extended by MyLinkAnnotator to process the pages.

Package com.ibm.wbi.protocol.http

HttpGenerator Extended by SetupGenerator and SetupResultGenerator.

Package com.ibm.wbi.persistent

Section
Used in the initialization and in SetupResultGenerator to store and retrieve plugin settings.

The Source

AnnotateUrl.java: Contains the entire plugin source.
annotateUrl.reg: Contains the necessary code to register the plugin with WBI. Registration is done through WBI during runtime.