Toolkit:  Modifying the Treebrowser

Purpose

This Toolkit page describes how to modify the Treebrowser.  This applies to the Rational Unified Process (RUP), and also your project Web if it uses the Treebrowser applet. The RUP Treebrowser organization is defined in five menu files; the main "tree.dat" and four submenu files.

Note that the Project Web Template and the example organization webs included in RUP, use only one menu file; "tree.dat". This file contains all the information regarding the Treebrowser organization.

Overview

To modify the Treebrowser:

1. Understanding the Treebrowser and it's corresponding menu files (*.dat)
2. Adding to the Treebrowser
3. Adding links to outside pages
4. The impact of modifying the Treebrowser
5. Verify your modifications

1. Understanding the Treebrowser and it's corresponding menu files (*.dat)

The left frame contains a Treebrowser with links to all pages in the Web site, as shown here.

Several files control the Treebrowser's behavior:

Each row in the tree.dat file consists of seven fields, separated by a "*". See Toolkit: The Treebrowser applet for a more detailed specification of this format. The following examples show different usage patterns for defining menu items in the Treebrowser. First, a brief description of each of the seven fields :

1. Defines the level in the tree
2. The menu item title
3. The path to a file location relative to the tree.dat location
4. Defines the target frame in which the page (in 3) is to be displayed
5. Icon to use when menu item is collapsed
6. Icon to use when menu item is expanded
7. Indicates whether the item should be expanded ('t') or not ('f') when the Treebrowser is initially displayed.

Example 1:
A link to a page within the RUP folder structure:

0*Glossary*../process/glossary.htm* *bookc.gif*booko.gif*f*

The target frame in this example is set to a whitespace character to indicate that the page will be opened in the main frame of the same browser session.

0*Rational*http://www.rational.com*_blank*bookc.gif*booko.gif*f*

The file to open in this example is a URL to an external web site. The target-frame field is set to "_blank" to open a new Web browser window.

Example 3:
A reference to the roles subtree from the main tree.dat file:

0*Role Sets*../process/workers/ovu_works.htm* *workers.gif*workers.gif*f*
1*Role Sets*rpw_role_subtree.dat* *workers.gif*workers.gif*f*

Example 4:
The format of menu entries within a subtree menu file (for example, rpw_role_subtree.dat):

0*Additional Role Set*../process/workers/wks_others.htm* *workers.gif*workers.gif*f*
1*Any Role*../process/workers/wk_any.htm* *workers.gif*workers.gif*f*

For a detailed explanation of the tree.dat and the subtree files, see "The data files" in the Treebrowser documentation.

2. Adding to the Treebrowser

An easy way to modify the RUP, and/or your project Web, is to add links to your own material in the Treebrowser.

For example, the beginning of the tree.dat file in the RUP looks like this:

If you want to add entries in the Treebrowser, add new rows in the tree.dat file. For example, if you want to add an entry at the top-level to "Our Own Process" and a link to a page "Our Design Guidelines" one level below, the tree.dat would look as follows:

The modified RUP Treebrowser would then look like this:

3. Adding Links to Outside Pages

When you add links to pages outside of the Web site structure, we recommend that these pages are opened in a new Web-browser window. This is most important for links added to the RUP— if you do not display the page in a new Web-browser window, it will be displayed in the main frame, which may cause the navigation buttons to create JavaScript errors. The reason for this is that the navigation buttons must have read access to the page.

• In the Treebrowser: Set the target-frame field to "_blank".
• In Web pages: If you have hyperlinks in ordinary Web pages to external pages, you should make sure that the target frame for the hyperlink is a new window. The HTML code for such a hyperlink will look as follows:

<a href="another page" target="_blank">another pages<a>

4. The impact of modifying the Treebrowser

Starting with the spring 2001 release (version 2001.04.00) of the RUP, the Web site that you are looking at is a result of an automated generation from an underlying RUP process model expressed using The Unified Modeling Language. The modeling and publication of web sites are done in the tool Rational Process Workbench™ (RPW). See the RPW tool mentor section for further details. Here, we discuss how modifying the treebrowser impacts the process of republishing and future upgrades of the RUP web site.

If you don't use RPW for configuring the RUP, please refer to the page Basic Modification of The Rational Unified Process for details.

However, if you use RPW for process configuration, please be aware of the following issues :

• When RPW publishes a new version of the RUP web site, it preserves the changes the user has done to the Treebrowser. But all the files (after user's confirmation) in the selected output directory will be deleted. Thus, if you add your own files and link them up manually via the Treebrowser, ensure that these files are located outside the published RUP directory structure. Note that the recommended way of making modifications with RPW installed, is to make the changes to the underlying process model. Refer to RPW documentation for more details.
• If you want to change the order of any of the subtrees as they appear in the Treebrowser, you may alter this ordering manually in the menu files (see above) by moving rows up or down. Make sure you move the whole row, and ensure that you move rows within the subtree. These kind of changes will be merged with the new Treebrowser files resulting from the next web site publishing session.

5. Verify your modifications

After you have made your changes to the Treebrowser (tree.dat or any of it's subtree files), you will be able to view the result next time you load the RUP Web site. If you don't want to close down your Browser session, you are able to see the result by selecting <Refresh> in your browser. Note that the some Browsers require <Shift> + <Refresh> to reload properly.

If the Treebrowser does not load after a manual change, it is likely that there is an error in one or more of the changed rows. You should inspect the file(s) and carefully check that the format specified in Treebrowser Applet, section The Data Files is followed. Below is a list of typical mistakes :

1. Not seven fields in a row (count the number of '*').
2. Missed the whitespace character for the target frame.
3. One or more of the menu items does not have a parent item; for example, for an item at level 2, there's no corresponding level 1 item.
4. Typo in the file path, which results in a "This page cannot be displayed" error
5. Misspelled the name of an icon file, which results in a menu item without an associated icon.

Copyright  © 1987 - 2001 Rational Software Corporation

Rational Unified Process