HTMLSearch Plug-in

Overview

Nadege Quaine (nquaine@hotmail.com), the contributor of the tocjsbis plug-in, has also contributed this plug-in. As of this writing, the most current version of the plug-in is dated April 8, 2008 and is distributed as htmlsearch1.04.zip.

The HTMLSearch plug-in first runs the XHTML transform that comes with the DITA-OT and then runs an indexing application against those XHTML output files. HTMLSearch deposits the keyword index and the supporting JavaScript worker libraries in a subdirectory named search.

Figure 1. HTMLSearch JavaScript Output

Each of these JavaScript index files correlates discovered keywords to one or more numerals representing particular XHTML output topics.

Figure 2. HTMLSearch JavaScript Search Array

The keyword "ant," for example, appears in three XHTML topics. These target topics are referenced numerically (1, 2, 5) and indexed separately in the file search\htmlFileList.js.

Figure 3. HTMLSearch Keyword-to-Targte-File Array

When you open the default HTMLSearch web page (frameset.html) in the output directory, it opens three frames containing a keyword input box, some default information about the plug-in, and a splash screen.

Figure 4. HTMLSearch UI

Results from a keyword search are displayed in the right-hand pane.

Figure 5. HTMLSearch UI

Figure 6. HTMLSearch UI

Clicking a hyperlink in the results list displays the target topic containing the keyword in the same right-hand pane.

The plug-in works fine in all versions of the DITA-OT because it is really interacting with XHTML output from the DITA-OT, not Open Toolkit resources per se. Beyond minor variations in the way the HTML displays in different browsers, HTMLSearch output works reliably in all modern browsers.

Setup and configuration

The HTMLSearch plug-in is a free download from the Yahoo DITA-OT site.

http://tech.groups.yahoo.com/group/dita-users/files/Demos/

After you have unzipped this archive to a local directory, you can browse the README.txt file to get a feel for what HTMLSearch offers and how you can install it in your DITA-OT demo directory.

Figure 7. HTMLSearch Plug-in Installation

Installing the plug-in presents no surprises.

1. Copy the un-archived htmlsearch subdirectory into the demo subdirectory of your DITA Open Toolkit directory.
2. Open a shell command window from your DITA-OT directory.
3. Enter the following command to integrate the new plug-in or plug-ins with your current DITA-OT environment.

   ant -f integrator.xml

4. From the DITA-OT root directory, enter the following command to build the sample DITA topics.

   ant -f demo/htmlsearch/buildsample.xml xhtml2search

5. Load the newly generated demo\htmlsearch\out\frameset.html file in your browser.

That is about all that is involved with installing and configuring the plug-in.

Authoring

There are no DITA source-level authoring considerations for this plug-in; it works on XHTML output topics generated by the DITA-OT XHTML transform.

Integration

Integrating output from the HTMLSearch plug-in with tocjsbis output or with your local favorite HTML implementation is possible, but challenging. If you have some experience modifying (or hacking) HTML frames and JavaScript code, have at it. Otherwise, you might consider continuing to use HTMLSearch output as a stand-alone complement to your other output transformations.

Consider the following tips when planning your customization effort.

• Quotation marks in DITA map navtitles: If the navtitles in your DITA map file(s) contain quotation marks, remove them before running the HTMLSearch plug-in. HTMLSearch passes these quotation marks through to its indexed output, effectively breaking JavaScript syntax in the search\htmlFileInfoList.js file.
• Directory levels for XHTML output: The HTMLSearch plug-in writes the hyperlinked results of a keyword search to a frame named contentwin. The initial static HTML loaded into that frame lives in the output subdirectory named sub. The filepaths in the hyperlinks written to that frame, therefore, are relative to an HTML file in sub. If you are using default XHTML output from the tocjs or tocjsbis, you may need to edit the JavaScript code that builds that relative path. Test removing the three characters "../" in line 131 of search\nwSearchFnt.js if you need to adjust HTMLSearch hyperlink paths to match target directory paths from tocjsbis or other DITA-OT XHTML output transformations.

  linkString = "<li><a href=\"../"+tempPath+"\">"+tempTitle+"</a>";

• Target frame name for keyword search input box: The HTMLSearch plug-in loads its input box into a frame named "searchwin" in its default interface. To integrate that input box into a different set of named HTML frames, you will need to change the name of the input box frame from "searchwin" to the new target frame name in lines 32, 39, 47, 242, and 248 in search\nwSearchFnt.js. For example, change "searchwin" to "your_frame_name" in the following line in search\nwSearchFnt.js:

  expressionInput=parent.frames['searchwin'].document.ditaSearch_Form.textToSearch.value

• Target frame name for keyword search results: The HTMLSearch plug-in writes its list of keyword search results (hits) to a frame named "contentwin" in its default interface. To have those results displayed in a different frame in your implementation, you will need to change the name of the input box frame from "contentwin" to the new target frame name in lines 146 and 414 in search\nwSearchFnt.js. For example, change "contentwin" to "your_frame_name" in the following line:

  with (parent.frames['contentwin'].document) {

• Target frame name for target topics: The HTMLSearch plug-in displays target topics in the same "contentwin" frame as the search results. If you would like to have both the list of search results and displayed target topics displayed simultaneously in separate frames, you will need to change that way that HTMLSearch builds hyperlinks. Specifically, you'll need to add an HTML "target=framename" attribute to line 131 in search\nwSearchFnt.js. For example, insert the string target='topicwin' (or your_frame_name) into line 131. Here's the original ...

  linkString = "<li><a href=\"../"+tempPath+"\">"+tempTitle+"</a>";

  and the update ...

  linkString = "<li><a href=\"../"+tempPath+"\" target='topicwin'>"+tempTitle+"</a>";

  After this change, HTMLSearch builds hyperlinks in the keyword search results frame that specify a different target window for displaying target XHTML topics.

These are the most visible variables that you'll need to consider when customizing HTMLSearch output for your own help implementation.

Output

Although the customization process can sound scary, it does produce some very nice results. Here is a prototype Help implementation for my current company. The goal here is to integrate the output from HTMLSearch with output from tocjsbis in a garden-variety three-tab, multi-frame HTML shell. Initially, the search UI is linked to a Search tab.

Figure 8. Integrated HTMLSearch

When the customer clicks the Search tab, a re-implementation of the HTMLSearch UI is displayed.

Figure 9. Integrated HTMLSearch

Search results appear in a lower frame in the left-hand navigation frame.

Figure 10. Integrated HTMLSearch

When the customer clicks one of the hyperlinks in the results list, that topic is displayed in the right-hand frame.

Figure 11. Integrated HTMLSearch

Summary

Customizing HTMLSearch to integrate it with tocjsbis or other XHTML output transformations from the Open Toolkit goes a long way toward making DITA-generated Help more usable and familiar to contemporary audiences.