Online Training with Dunstan Thomas

Reporting with EA 15

In this new world of Social Distancing, remote working and remote delivery have become essential as we all adapt to being at home and away from the traditional meeting room environment. It is with this in mind that we are pleased to announce that this morning we have published an update to one of our popular online training courses, Reporting with Enterprise Architect.

The new version of this online self-study training session is made especially to work with Sparx Systems Enterprise Architect version 15.x and covers the following topics:

Reporting with Enterprise Architect v.15 - Agenda

• Introduction to Enterprise Architect
  • The main features of Enterprise Architect and its editions
  • The concept of repositories in Enterprise Architect;
    • Working with repositories
    • Structure of repositories
  • Provide an overview of version control with Enterprise Architect
    
    
• Publishing to HTML
  • Generating an HTML Report
  • Using your own logo
  • Customisation using Web Style Templates:
    • Creating a Web Style Template
      
      
• Publishing to a DOCX / PDF Document
  • Publishing to a DocX / PDF Document
  • Templates and the Template Editor
  • Completing the Template
  • Adding a Table to a Template
  • Generating the Document
    
    
• Cover Pages, Templates and Style Sheets
  • Cover Pages
  • Table of Contents
  • Style Sheets
  • Creating and applying a Style Sheet
    
    
• Combining Templates
  • Combining Templates
  • Creating a Model / Master Document
  • Template Fragments

Each of these topics is delivered as a lesson activity within Dunstan Thomas' learning site. These lessons are made up of reading materials, step by step exercises guiding you through the publication processes and supplementary video content to support those exercises.

Given the current climate, if you would like to know more about our off-the-sheld online training or to organise an instructor led remote learning webinar, please do not hesitate to This email address is being protected from spambots. You need JavaScript enabled to view it..

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

HTML Report 2, Electric Boogaloo

As a sequel to my previous article on how to edit the CSS generated by Enterprise Architect to personalise your generated HTML report I was prompted by Guillaume to create this follow up as he gave me an idea on how to make these changes prior to generation. As we have already identified the changes that we need to make in the previous article we can actually create our own customised version of the CSS EA would use and specify that this is then used as we create our HTML report.

So how do we do this?

Keeping in mind the list of changes that we need to make:

1. Change the attributes for .IndexHeader so that the logo fits within the header of the report.
2. Change the attributes for .IndexBody to cater for the changes that we have made to the header.
3. Change the attributes for #contentIFrame so that the content section of the report fills the correct amount of the screen.
4. Change the attributes of #tocIFrame so the table of content is displayed correctly.

With these changes in mind we are ready to get to work on defining our template. To do this you will need to fire up EA. At the bottom of your project browser you will see a tab labelled Resources, click this…

Having clicked this your view will change to…

You will then need to click into the section for Document Generation…

Next, right click Web Style Templates and choose Create HTML Template. This will bring up the following dialog…

Enter a name for your new template and a new window will open…

You can select any of the options listed in the left hand pane for editing by simply clicking on them. As the changes we are looking to make are relatively simple the only option that we need to concern ourselves with is CSS – Main. Click this option and you will see the following…

You will then see the CSS display itself in the right hand pane, navigate to the areas of interest by pressing ctrl+f and entering the headings outlined earlier. Clicking on the find next button will take you to these areas in the CSS and you can make the necessary changes. Once you have made the changes click save and then click close. With these actions complete you are now ready to generate a new HTML report that will automatically use your custom CSS.

As before right click on your project in the project browser and choose HTML Report…

Clicking this will display the familiar dialog…

Under the Style option you will now be able to have a drop down menu that will list the names of any custom templates that you have created. For this example, I have changed the style to be the CUSTOM template created earlier in this article, this means that when we generate our report EA will now use our predefined custom CSS rather than the standard set. We also need to specify our logo as before, then click Generate.

The result is that our HTML report has been generated with no changes to be made and that we can re-use our template every time that we need to create this kind of report…

Editing an HTML report generated from Enterprise Architect using CSS

Introduction

This article will walk you through the process of making a couple of simple tweaks to your HTML Report generated from Sparx Systems Enterprise Architect.

So what's the challenge here?

If you have ever needed to create a quick and simple report to walk a colleague or stakeholder through certain aspects of your model, then by far the quickest and easiest route is to generate an HTML Report from EA.

This will create an HTML version of your project locally that can be navigated & drilled down into (but not updated etc). When creating this report, you have the option to include your own logo as a way of adding a little bit of an extra visual engagement to your publication.

The challenge that you can, and will likely, run into is that there is a set size for the logo that EA does not tell you about and you will not see the effect of until you view the report and see that your logo is cut off by content.

How do I fix this?

To start you will need to generate an HTML report from your model. If you are not sure of how to do this simply right click the root node of your model in EA and choose “HTML Report” from the menu…



When you click this option you will be presented with the following dialog…



In this dialog check all the options that you want to include in your report and specify your output destination folder and your logo image. When ready, click “Generate” and you will have a progress bar pop up momentarily while EA generates your report.

When this process has finished you can either click “View” or navigate to your Output folder & open the file “Index.htm” (there will be other files & folders generated as well but for now this all you will need).

When opened you will see something like this….



As you can see, the logo is too big for the report and there is no way to address this issue inside of EA.

So what do we do?

The Solution!

The first thing we do is to open up the HTML report using Chrome. This itself posed its own challenge initially as out of the box Chrome does not really support file based URLs, but there is a work around for this (thanks to Phil Chudley for showing me this).

Firstly, find your shortcut for Chrome, right click it and choose “Properties”. When the Properties window appears locate the section labelled “Target” and add the following to the end of the information there:

--allow-file-access-from-files

Make sure that you include a space between …chrome.exe” and the string shown above for this to work.



We now need to make some changes to the HTML report.

Earlier I mentioned that there are several files generated at your output destination when you create this HTML report. One of those folders is titled CSS and contains two files, you will need to open the “ea.css”, personally I use Notepad for this but there are a host of tools you could use.

With your CSS file open and with Chrome displaying your report it’s time to start editing.

Hover your cursor over your logo, right click and choose the “Inspect” tool…



This will open up a new Chrome window displaying the developer tools…



The sections that we will need to pay attention to are:

• IndexHeader; this will be apparent immediately if you choose to inspect the logo
• IndexBody; you will see this below IndexHeader but you will also need to expand this section clicking the triangular icon to the left of it to expose the other areas we need:
  • tocIFrame; this is the section of the page containing the model tree in your report
  • contentIFrame; this is the main section of your report that displays your information

.IndexHeader

This is the CSS controlling the display of this section of the report. The important factor here is the height property. As you can see, it is by default only 60 pixels tall and in our example the logo is larger than this.

To adjust this click into the area where it displays “60px”. You can overwrite this with your desired figure or you can adjust it your logo by using the up arrow to increase the height one pixel at a time. In our example I changed mine to 91px.

With your ea.css file open you will need to find .IndexHeader in there and adjust the height to your new value. Save but don’t close your ea.css file.

You will, for now, still see something similar to this…



What we now need to do is make the body of our report work with the changes that we have made to the header.

To do this we need to make some changes to the section of the CSS for .IndexBody

.IndexBody

Using the developer tools window you now need to pay attention to the CSS for this section…



The change we need to make here is to the position attribute from position: absolute; to position: inherit;

You will see that this changes the position of the body of the report allowing the header section to be fully displayed along with our logo...



Make sure to adjust this section in your ea.css file & save.

You will notice that this has created a new issue in that the frame housing our table of contents has now shrunk. You can still expand and use this section as you normally would however it quickly results in excessive scrolling. This is something that we don’t want and so we will need to make a couple more changes to fix this.

#contentIFrame

This is the frame that displays our content & in the developer tools it will look like this…



In the developer tools this section will appear grey and so cannot be edited there. Instead you will need to locate this section in the ea.css file and make the change there without previewing it.

The change that you will need to make is to the attribute height: 100%; to instead be height: -webkit-fill-available; as shown above. Then save your ea.css file. This will set the size for the main display frame.

Next we need to look at the frame for the table of contents.

#tocIFrame

To make our Iframe look correct we will need to make the same change as we have just made to the content frame…



Again the change that you will need to make is to the attribute height: 100%; to instead be height: -webkit-fill-available; as shown above.

Then save your ea.css file.

You have now completed the changes necessary to have your HTML report display properly and with your own logo. From now on you will see something akin to this upon opening…



Everything is now exactly where you would expect it to be and in a useable fashion.

There is something to bear in mind should you choose to use this method. If after following this method, you need to make changes to your model & regenerate the HTML report to the same output destination then your changes to the CSS will be overwritten as well.

To get around this, before you regenerate your HTML report simply rename the ea.css file to something else e.g. ea – NEW.css and then regenerate the report.

What you find now is that in the CSS folder in your output destination there will now be another file called ea.css and this is the one that the report will default to. Simply delete this file and rename the ea – NEW.css file back to ea.css having done this your updated report will open & use your modified CSS still.

Obviously there is a lot more styling you could apply by using the CSS, this is just a simple fix for a particularly common bugbear with the HTML Report.

You can find more content like this on our YouTube channel, Facebook and Twitter.

Creating Charts in Enterprise Architect to Aid Decision Making

Date: September 2014

Mr Scott Hebbard, Communications Manager at Sparx Systems, will show how Charts in Enterprise Architect can help you manage projects, communicate strategy, identify trends, track KPI's and make informed decisions.

In this webinar you will learn how to:

• Place Charts and Graphs on diagrams, group them to display an interactive project dashboard and include them in generated reports
• Source data from the model, from specific Packages within the model, or from a custom SQL query that extracts the information from the model
• Create burn down charts and time series graphs that are automatically updated by Enterprise Architect on a regular basis.

Register Here ...