Creating Navigable Models for HTML Publication

By Phil Chudley, Prinicipal Consultant at Dunstan Thomas Consulting

Background

Once a model has been developed in Enterprise Architect, it can be shared to users who do not have Enterprise Architect by publishing the model to HTML where the model can be viewed in a browser.

However, out of the box, this common method of publication to HTML suffers from the following problems:

1. Unless the model is organised very logically, the non-Enterprise Architect user can struggle to find their way around the model.
2. The presence of the Project Browser tree in the Web Page(s), can be confusing to the non-Enterprise Architect user where too much information is provided.

In reality, the non-Enterprise Architect user is most interested in the diagrams, and ideally would wish to navigate the model using these diagrams.

Navigation techniques are already built-in to Enterprise Architect, namely:

• Composite Elements.
• Hyperlinks.
• Navigation Cells.

If a model is built so that it can be navigated purely via diagrams using the techniques above, then the presence of the project browser tree in the HTML publication is rather irrelevant. The question is how can this project browser tree be removed from the web pages? The answer can be found in this article.

Creating a Model that can be Navigable via Diagrams

This section uses built-in features of Enterprise Architect. For an example, let us consider the following model that has been built already in Enterprise Architect:

This model is a “typical” UML model supplemented with Requirements, User Interface Screens and a Dashboard. As its stands it is quite difficult to navigate for the non-Enterprise Architect user, therefore we add to the model the following:

• Table of Contents diagrams that contain Navigation Cells to other diagrams.

A navigation cell is created very easily by:

1. Creating a diagram (I use the EA Extended Custom diagram type) in a Package.
2. Navigate to a diagram.
3. Drag and drop this diagram to the diagram created in step 1) and choose Navigation Cell from the list of options.
4. Choose an appropriate image.

For the model illustrated above, we begin by:

1. Adding a View named TOC (or Table of Contents) to the model root.
2. Move this to be the first view in the model.
3. Add to this View a diagram (for example an EA Extended Custom diagram type).

This is illustrated below:

The next step is to add navigation cells to this newly created diagram and there are two basic approaches:

1. Add a navigation cell for each diagram within the model to the diagram named TOC.
2. Create “TOC” diagrams for each view / package and created navigation cells for these lower level TOC diagrams.

Which option you use depends upon the complexity of the model, in this example I used option 2) which resulted in the TOC diagram being populated with navigation cells as shown below:

As an example of a lower level TOC diagram, consider the package named User Interface which is shown expanded below:

Each of the packages inside User Interface has a User Interface diagram. Generally I place one diagram in one package.

Creating navigation cells for these diagrams yields the TOC diagram for the User Interface package as shown below:

This process is repeated for other Views and Packages.

We now have a model that is navigable entirely via diagrams commencing with the top level TOC diagram.

In this example I created a “back link” to the level above, using a hyperlink and setting the Behavior property Printable to be false.

The final step is to ensure that when the model opens, the TOC diagram is displayed by default. This is achieved by:

1. Opening the TOC diagram.
2. Select the Layout Ribbon.
3. Select Manage → Set as Model Default.

Publishing to HTML

The result of selecting the Model Root node and using the Publish to HTML function, out of the box is as shown below:

The modifications we are going to make are as follows:

1. Change the header image.
2. Remove the Project and Advanced information from the bottom of the diagram.
3. Remove the Project Browser Navigation tree.

Making the Modifications

Changing the Header Image

This is very easy to do, as there is an option on the HTML generation dialog to navigate to and select an alternate image. However, there is a “gottcha”. So that the chosen image will fit in the frame at the top of the HTML page, it must be less than or equal to 60px in height.

In this section, I will show you how to customize the HTML output so that the frame resizes to fit the height of your image.

The following steps are used:

1. Discover the height of your image (this can be achieved with Windows File Explorer by positioning the mouse on the image file and examining the tool tip that displays). The image that I am going to use has a height of 56px.
2. Using the Resources View, open the section named Web Style Templates, right-click and select Create New HTML Template.
3. Enter a suitable name and click OK.
4. In the dialog that displays the list of Templates, select the template named CSS – Main.
5. Scroll down to line 248 as shown below:
   
6. Change line 252 to be the height of your image + 1, in my example this is 57.
7. Similarly, change line 259 to be the height of your image, in my example this is 56:
   
8. Click Save.

Remove the Project and Advanced information from the bottom of the diagram

The following steps are used, assuming that the dialog showing the HTML Templates is still visible, if not, right click your Web Style Template in the resources and select Modify HTML Template:

1. Select the Template named Body – Diagram:
   
2. Delete lines 13 through 32 inclusive:
   
3. Click Save.

Remove the Project Browser Navigation tree

Saving the best for last, our final modification is to remove the Project Browser Tree. To achieve this the Javascript Template needs modification as follows:

1. Select the Template named Javascript:
   
2. Scroll down to line 520 which should be the function named resizePage().
3. Scroll down to line 549 and replace this line with the following lines of Javascript:
   
4. Scroll back to line 85 which should be the function named initLoad(src, toc, home).
5. Insert the following line of Javascript between lines 128 and 129:
   
6. As a check the modification above should be as shown below:
   
7. Click Save and then Click Close.

The Result

To view the effect of the changes, re-publish the model to HTML this time selecting your Web Style Template and navigating to your Image:

The result as shown in the Browser is as shown below:

Conclusion

The next step would be to modify the HTML templates such that when the user clicks an element which does not link to a diagram, nothing happens rather than the default behavior of displaying an element properties screen. Alternatively, the element properties screen could be modified to display just name and notes for example. Once I have worked out how to do this, I will share this in another tutorial.

Phil Chudley
Principal Consultant
Dunstan Thomas Consulting
Follow me on Twitter @SparxEAGuru