Extending techexplorer via Add-ins

The DocumentExplorer Add-in

The DocumentExplorer add-in displays the document hierarchy in the form of a tree as well as provides a graphical interface for Document Object Model operations. As a result, the DocumentExplorer allows you to view and edit techexplorer documents right in your web browser!

In this section, we start by explaining how to use the DocumentExplorer. Indeed, the DocumentExplorer proves to be a valuable "debugging" tool when implementing add-ins and Java applets that make use of the Document Object Model API. For the remainder of this section we describe the implementation details of the DocumentExplorer with an eye towards developing DOM add-ins.

Using the DocumentExplorer Add-in

Like all techexplorer add-ins, the add-in dll must reside in the reside in the techexplorer\Bin subdirectory of the web browser Plugins folder. The Professional Edition installation automatically installs all of the "default" add-ins in the appropriate location.

The \evalLink control sequence allows you to embed a link to the DocumentExplorer add-in. To use the DocumentExplorer add-in include the following in any techexplorer document:

\evalLink{IBM techexplorer Document Explorer Add-In}{application/x-document-explorer-string} {}{Press here for a DocumentExplorer test}

Check out an example. In the example, to activate the DocumentExplorer click on Press here for a DocumentExplorer test. When started, the Document Explorer will display a tree view of the document.

You can click on the "+" or "-" icons (on the MAC, click on the triangular arrows) to expand or collapse the tree as you explore the document structure.

Interacting with the Document

The DocumentExplorer provides context menu access to many of the operations defined by the Document Object Model API. Simply right click on a node and select an operation from the menu.

A "Node Panel" appears when using Document Object Model Node methods.

The Node Panel allows you to select what types of nodes to create. In the case of Text nodes, you must also provide a value. The "Recycled Nodes" area allows you to select from cloned or removed nodes.

DocumentExplorer Trail Maps

Appending a paragraph

1. Expand the document tree until you see all the children of #document\vertical-list.
2. Click on the vertical-list node
3. Right click on the mouse and pop up the menu, select Operations\Append Child...
4. The Node Panel appears.
5. Pull down the "Node Type" combo box, find paragraph and select it.
6. Click on the OK button
7. Notice that a new paragraph node appears at the end of the tree.
8. Select the paragraph node you just created by clicking on it.
9. Right click on the mouse and pop up the menu, select Operations\Append Child...
10. The Node Panel appears
11. Make sure #text is the Node Type, if not select it.
12. Click into the "Node Value" text box.
13. Input the following text to the textbook: "This is an example of how to insert a paragraph into a document via Document Explorer".
14. Click on the OK button.
15. Notice that a text node has become a child of paragraph node and the text you type in is the child of the text node.
16. Click on the OK button of Document Explorer.
17. Notice that a new paragraph appears at the end of the document.

Removing a paragraph

1. Click on the last paragraph (the one that you just created) node in vertical-list node to select it.
2. Right click on the mouse and pop up the menu, select Operations\Remove Child...
3. Click on the OK button of Document Explorer.
4. Notice that the paragraph is gone from the document.

Replace a heading

1. Click on the first paragraph node in vertical-list node to select it.
2. Right click on the mouse and pop up the menu, select Operations\Clone node...
3. Click on the heading node in vertical-list node to select it.
4. Right click on the mouse and pop up the menu, select Operations\Replace Child...
5. The Node Panel appears
6. Click on the "Select From Recycled Nodes" checkbook
7. Select the paragraph node from "Recycled Nodes".
8. Click on the OK button of Node Panel.
9. Notice that the heading node is replaced from the cloned paragraph node.
10. Click on the OK button of Document Explorer.
11. Notice that there are two Document Explorer links in the document and the heading of the document is gone.

Inside the DocumentExplorer Add-in

The techexplorer add-in SDK contains the C/C++ source and makefiles for all of supplied add-ins. In the case of the DocumentExplorer add-in, the source code resides in the AddInSDK\DocumentExplorer\Win32 subdirectory. For default installations of techexplorer, the full path of the Document Explorer SDK is

C:\Program Files\IBM\techexplorer Hypermedia Browser\AddInSDK\DocumentExplorer\Win32

On the Mac the folder names are AddInSDK:DocumentExplorer:Mac and Macintosh HD:IBM techexplorer:AddInSDK:DocumentExplorer:Mac respectively.

The DocumentExplorer was implemented using the Microsoft Visual C++ 6.0 compiler. To build the add-in you can either load the TADocumentExplorer.dsw project into Visual C++ 6.0 or use the TADocumentExplorer.mak file as follows:

nmake -f TADocumentExplorer.mak

Once the build is complete, be sure to move the TADocumentExplorer.dll to the Addin subdirectory of your techexplorer folder.

On the Mac the distributed project files are XML text files. After the build, move the shared library to the Addin subdirectory of your techexplorer folder.

The DocumentExplorer project uses the add-in SDK "interface" (TaApi.h, TaApi.cpp) as well as the Document Object Model implementation and interface code:

The TADocumentExplorer class (TADocumentExplorer.h, TADocumentExplorer.cpp) is the core of the DocumentExplorer application. TADocumentExplorer provides implementations of the seven techexplorer add-in API methods and is responsible for starting the main dialog when the AddInEvaluate function is invoked.

Once started, the DocumentExplorerDialog class uses the DOMFactory to obtain an instance of the TEDocument class. The TEDocument instance is used to populates the document tree and serves as the entry point for accessing the objects in the techexplorer document. The DocumentExplorerDialog instance handles all of the context menu operations and uses the NodePanel class to handle the Document Object Model operations.