How-to: Functional Documentation in Enterprise Architect

Written by:

Carolien de Langen

Chan Kerste

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.

Try RepoDoc, a new way of documenting your repository.

It’s easy to use, powerful and we offer it for free to anyone willing to test or help.

What is RepoDoc?

A document generator add-in for Enterprise Architect.

What makes it special?

• uses Liquid templates that are easy to create, modify and maintain,
• offers flexible repository filtering capabilities,
• makes non-linear document generation possible,
• supports a wide range of document formats including, but not limited to, HTML, LaTeX, PDF, Markdown, AsciiDoc, CSV, XML or JSON files, SVG, source codes in different languages,
• contains a built-in post processor.

How can you help?

• try it out and submit your wishes for a must/nice to have functionality,
• write a new interesting template or let us know what kind of template would you need.

What you can achieve?

Here are few examples of documents, generated with RepoDoc. Find more at repodoc.archimetes.com.

UML model overview (HTML)

Requirements catalogue (LaTeX)

Dependency graphs (DOT/Graphviz)

Dependencies between UML elements.

Dependencies between Archimate elements.

Class diagram overview (AsciiDoc)

Package list (JSON)

About

RepoDoc is a document generator for Enterprise Architect able to produce a variety of document formats using templates written in any text editor.

How it works

RepoDoc takes a document template and a starting package as input. It outputs a plain text document together with repository artifacts specified in the template and taken from the repository. An optional profile may be specified to instruct RepoDoc to post-process the document with a third party software (like Asciidoctor or Pandoc).

RepoDoc uses plain text templates and an easy to learn Liquid template language. This allows to output a broad range of different plain text formats like CSV, XML or JSON, but also to post-process the result in various third party backends to produce an office document like DOCX. It also offers new possibilities when iterating repository like multiple iterations, custom loops, conditional expressions and more.

How to use

1. Download and install latest RepoDoc bundle.
2. Start Enterprise Architect and open your project.
3. Select RepoDoc from the Specialize ribbon and open its control panel.
4. Click Generate.
5. Click View.

Features

✅ Markup languages

Use your favorite markup language like Markdown or AsciiDoc to prepare your document then convert the output to a HTML or DOCX with a single click.

✅ Conditional expressions

Document only elements you need and when you need them. Write logical conditions based on name, type or number of child elements. No more empty sections or tables in the output document.

{%- for element in package.elements -%}
  {%- if element.type == "Actor" -%}
    Documenting actor name {{ element.name }}
    and actor notes {% if element.notes != "" %}{{ element.notes }}{% endif %}
    (but only if non empty).
  {%- endif -%}
{%- endfor -%}

✅ Multiple iterations

Iterate and document your repository items multiple times. Create requirements section first and then add a use case section. Everything aligned in a single document.

Now I'm documenting only actors.
{%- for element in package.elements -%}
  {%- if element.type == "Actor" -%}
    ...
  {%- endif -%}
{%- endfor -%}
And now I'm documenting only use cases.
{%- for element in package.elements -%}
  {%- if element.type == "UseCase" -%}
    ...
  {%- endif -%}
{%- endfor -%}

✅ Output redirection

Output images or artifacts to individual files. Export data in different formats to multiple files.

✅ Relationships & analysis

Walk through the connections for elements and diagram objects and document important ones. Analyze and document impacts with recursive templates.

✅ Version control

RepoDoc uses plain text Liquid templates that are ideal for version control system. Track changes in your templates and tag them easily.

Want more?

Select another template or write quickly your own with an easy to learn language. Find out more about RepoDoc at repodoc.archimetes.com.

The EA User Group returns to London this May

On the 17th May the annual London meeting of the Enterprise Architect User Group will be happening at Skillsmatter's Code Node venue.

The final agenda has been confirmed today and we've got a great day lined up...

Agenda

Tickets

Tickets are available from the EA User Group website at the price of £65.00 +Vat per person.

Introduction

In order to provide a consistent look-and-feel to documents (RTF/DOCX/PDF) produced from Sparx Systems Enterprise Architect, Sparx Systems provided the facility of a Style sheet so that when applied, the styles defined in the style sheet override the corresponding styles used within the document template(s).

A style sheet is selected when a document is to be generated using either:

• An artefact selected in the Project Browser such as a package.

• A Master Document.

The main challenge faced by EA users is the creation of the style sheet, this tutorial provides you with the techniques for the creation and use of a style sheet.

Please see the attached tutorial for full details of this process.

Sparx Systems Enterprise Architect version 11 is very close to being released (I am currently using Release Candidate 2), and promises a host of new and improved functionality. It’s a good time to revisit the built-in reporting, and reflect on how the stepwise improvements during the Enterprise Architect 10 release series have been rolled-up into a streamlined user experience…

Improving the dialogue

You can right-click on a model root in the Project Browser and view the improved Generate Documentation dialog window. In particular, you will see that the Generate tab contains some additional fields to enable the easy selection of:         

• Table of Contents
• Stylesheet
•  Cover Page
• Diagram Theme

Figure 1: Generate documentation dialog

Previous versions of Sparx Enterprise Architect already provided a skilled operator with the ability to create all of these things. However, the dialogue changes (along with some other enhancements in the report template editor) are aimed at making things easier and more obvious for operators with beginning and intermediate levels of skill.

Generate documentation, not just RTF

If you click Generate Documentation | Generate | Output Format then you will see that you have options to generate Microsoft Document Format (DOCX), alongside the previously available Portable Document Format (PDF) and Rich Text Format (RTF).

Figure 2: Selecting an output format

You might not be aware that Microsoft has discontinued making enhancements its proprietary RTF specification, and that some new features in Word 2010 and later versions will not save properly into the RTF format. The new format will enable Sparx Systems Enterprise Architect to continue inter-operating with the Microsoft proprietary world.

Your model’s structure can be orthogonal to your project documents

Did you know that your model’s structure need not be dictated by the project reports that you want to generate? You can use Documentation Diagrams, containing Master Document elements, to coordinate Document Model elements and/or Template Fragments into producing production ready project documentation.

Figure 3: Overview of documentation elements

Model Documents can act as drag-and-drop targets for packages from the Project Browser, or get populated by user defined element searches, to create individually formatted sections for your documents. Fine grained control over document subsections can achieved through using Fragments, which can use custom templates, scripts (either JavaScript, JScript or VBScript), or SQL queries. Each Model Document can be formatted using a custom template, if required.

Exploring the rich report generation functionality of Sparx Enterprise Architect version 11 can take some time, and creating advanced custom templates can be quite a specialized task. However, it is important to remember that only a few people in your organization might need to develop the skills to create custom templates, whilst everyone else just needs to click through the Generate Documentation dialog, or a pre-prepared Documentation Diagram.

Ideally, you will be able to create a Documentation Diagram containing a Master Document for each of the project documents you need to create. Each document can then be right-clicked and produced on demand.

Figure 4: Example project documentation

Of course, power users of Sparx Enterprise Architect can create a script to produce documentation for the entire project, on demand, with a single mouse click!