Generate as HTML

Overview

This helpers generates a HTML version of the model or any part of it.

Applicable To	All
Menu Entry	Power Pack  Reporting Tools  Model Report  Generate as HTML / Open Generated HTML
Demonstration	Watch the Video

The helper may also be launched from the toolbar* (select a scope element first):

*The toolbar button always generates a new report however if the property below is set to false then instead it opens any previously generate HTML report for performance. If no report is available for the selected element, then it is generated and opened. If the model has changed, to force a new report, use the Generate as HTML menu or toggle the property back to true:

RhapsodyPowerPack.GenerateAsHTML.ToolbarButtonForcesGenerate

Operation

The helper iterates over the model tree starting from the selected element and builds it as a set of navigable HTML pages:

Configuring Generation Using Properties

Note that unless otherwise noted, all properties mentioned may be set on a package or project (properties are read on launch so setting properties on a sub package and launching from the project will have no effect). This does mean that you may generate separate documentation for different parts of the model using different property values.

Documenting Profiles

Note that if the report is generated from the project, Profiles are not included for performance reasons. However, this may be changed by specifying a comma-separated list of profiles to include using the following property (which must be set at project level):

RhapsodyPowerPack.GenerateAsHTML.IncludeProfiles

Alternatively, the helper may be launched directly from a profile to document it separately.

The Browser Tree

By default, the tree uses categories, but this may be changed using the following property:

RhapsodyPowerPack.GenerateAsHTML.OrganizeTree

Icons are extracted from Rhapsody and copied into an Icons sub-folder in the generated report folder and displayed in the tree. This may be disabled using the following property:

RhapsodyPowerPack.GenerateAsHTML.UseIconsInTree

The Diagrams Tab

All diagrams in scope are collected on the Diagrams tab which by default reports them in a flat list with category headings. Sub-tabs may be used instead by setting the following property:

RhapsodyPowerPack.GenerateAsHTML.UseSubTabsInDiagramsTab

Custom Tabs

In addition to diagrams, other elements may also be presented on custom tabs, see Configuring Custom Tabs

Metrics

If Metrics are enabled, these are collected onto a Metrics tab.

Diagrams

Diagrams are extracted from Rhapsody and presented. The generated HTML pages contain image maps so elements on the diagram are navigable

Descriptions

RTF descriptions are converted into HTML in the report, however there are some limitations since Rhapsody’s RTF is non-standard and converting it to HTML can be tricky.

Hyperlinks

· There is no facility in Rhapsody get the target of a hyperlink embedded into RTF (the API returns text that only contains the name of the model element) and so cannot become a true hyperlink in the generated html.

· Hyperlinks in bulleted lists are currently not supported and may result in a garbled description on the report.

Remote Artifacts

Remote artifacts are included in the report only if they are loaded into the model at the time of report generation. Remote artifact pages have an additional button to navigate into the ELM server (Locate in Web).

Limitation: The Rhapsody API provides no information about any current Global Configuration (GC), only the base URI so after navigation, manual selection of the correct GC may be required.

Table Views

By default, table views are reported but without their rendered content. To include the rendered table content, set the following property to true:

RhapsodyPowerPack.GenerateAsHTML.IncludeTableContent

Note that for Rhapsody to produce the rendered content it must open the table view. In Rhapsody 10 this happens invisibly (although you may see messages in the output window if the table uses embedded java) but in Rhapsody 9 the table opening is more obvious.

Matrix Views

By default, matrix views are reported but without their rendered content. If the option is enabled, then rendered matrix views are presented on a separate tab:

To include the rendered content, set the following property:

RhapsodyPowerPack.GenerateAsHTML.IncludeMatrixContent

The property has the following values:

· None – no rendered content

· Static – Rhapsody provides rendered content as html

· Dynamic – The helper generates is own rendered content, allowing more advanced layout and filtering options. Note this can increase processing time significantly (especially for matrix views scoped by project) as the Rhapsody API only provides information about the cell data. The row/column data must be manually extracted by iterating over the matrix scope(s).

Dynamic Rendering

Dynamically rendered matrix views allow dynamic filtering of the data using regular expressions:

Dynamic Rendering Options

The following properties may be used to modify the rendered matrix content:

Navigation Links

By default, the navigable links on the dynamically generated matrix view navigate directly to Rhapsody. This is by design as internal navigation would instead shift focus away from the matrix (and Rhapsody has no Back button). However, if you prefer a fully self-contained report where these links navigate internally, set the following property to true:

RhapsodyPowerPack.GenerateAsHTML.UseInternalLinksForMatrixViews

Cell Data

Cells may present the name, icon or both. If both properties are set to false, then the report reverts to the default and shows both.

Model.MatrixView.ShowText

Model.MatrixView.ShowIcons

Row and Column Sorting

Rows and columns may be sorted using the following properties:

Model.MatrixView.RowSorting

Model.MatrixView.ColumnRowSorting

Possible values:

· Original (Uses the same sort order as Rhapsody)

· Alphabetical

· ReverseAlphabetical

Column Titles

The orientation of the titles in the column headers may be set using:

Model.MatrixView.VerticalColumnTitles

Pre-Filtering

In addition to the dynamically applied filters mentioned above, the matrix may be pre-filtered by providing regular expressions in these properties:

Model.MatrixView.CellRegexFilter

Model.MatrixView.ColumnRegexFilter

Model.MatrixView.RowRegexFilter

If the matrix view has pre-filters, the report indicates this:

Reducing Scope

Rhapsody only allows packages/project as the ‘from’ and ‘to’ scope which makes them much less usable for fine grained elements like operations. The following properties may be used to reduce the scope of the generated matrix:

Model.MatrixView.ColumnClassifiers

Model.MatrixView.RowClassifiers

Both properties are comma-separated lists of names (leave the properties empty to keep the scope as-is).

If these properties are used then before rendering the matrix, the helper checks each row/column element by looking ‘up the tree’ in the model browser. If a Class, Use Case or Actor is found in that ownership tree with one of the specified names then that row/column is presented in the matrix.

If not, then it is omitted. If a package is found first, then the row/column is omitted.

In this way the matrix may be scoped down to only those elements owned by the specified classifiers allowing much more focussed matrix views that use elements such as operations, attributes, transitions and so on.

If these properties are used, then the generated matrix is given the same pre-filter message described above.

Switching Rows and Columns

To reliably switch rows and columns in the generated matrix, do not use the Switch Rows and Columns button in Rhapsody. If this button is used, the row/column data Rhapsody provides through the API is indeed switched but there is no way for a helper to detect that the button was used and so the labels in the generated report will be incorrect (also that button is transient – Rhapsody discards the setting when the matrix view is closed). Instead use the property below – this can be read by the reporter and will be kept when the matrix view is closed:

Model.MatrixView.SwitchRowsCols

Note also that Rhapsody completely ignores this property whilst the matrix is open – be sure to close the matrix so that this property change takes effect before running a report.

Hiding Empty Cells

Unlike switching rows and columns, the Rhapsody API does provide a method to detect if you have toggled empty rows / columns temporarily using the toolbar. The reporter does use this function so be aware that if you set the corresponding HideEmptyRowsCols property to true on the matrix view and then report on it then the currently displayed matrix data will be reported (which may conflict with the property setting) this may cause slight confusion if you are viewing the locally overridden properties on the Details tab of the report.

Properties

If the following property is true, then the generated page for a model element includes section(s) for any locally overridden properties* on that element:

RhapsodyPowerPack.GenerateAsHTML.IncludeProperties

Note that properties that start with Format. are automatically filtered out just as Rhapsody does in its own Features dialog. However, these properties are visible using Generate Overridden Properties Report.

There are two possible sections, ‘regular’ properties and conditional properties (these are properties whose value starts with “?<IsConditionalProperty>“).

Conditional property sections include both the original ‘raw’ value and the value after the condition(s) have been evaluated:

Out of Scope Elements

All elements in scope (that is they are in the browser tree of the currently selected element) are fully processed and show their nested elements, references and so on. Out of scope elements (found by some reference to an in-scope element) are minimally processed to allow navigation. For example, if the helper is launched from a diagram, then any elements on that diagram would be considered ‘out of scope’ and would have minimal html pages reporting basic information such as name, description and a Locate in Rhapsody button to allow navigation. For example:

Navigation

Navigation into Rhapsody is achieved through the Power Pack Web Link Listener.

Opening the Generated Documentation

Once generated the starting index.html page is opened either in Rhapsody or in an external browser (or both) depending on the value of the following property:

RhapsodyPowerPack.ReportingTools.OpenInBrowser

Note that documentation opened in Rhapsody uses the same tab each time, but Rhapsody does not automatically switch to this tab so if you have selected a different tab (for example a diagram) then you must manually select the index.html tab to view the generated documentation.

Previously generated documentation for the selected element may be opened without regenerating using the menu Power Pack  Reporting Tools  Model Report  Open Generated HTML

Generation Folder

All documentation is generated into a folder with the same name as the selected model element. These folders are in turn created in a base folder which by default is entitled HTML Reports which is created in the same folder as the project .rpy(x) file. This may be changed using the following property which may be a relative path (to the project file):

RhapsodyPowerPack.GenerateAsHTML.BaseGenerationFolder

Note that if the generation folder for the selected element already exists, it is deleted and recreated each time generation is invoked.

Display Properties

The generated report layout may be customized using the following properties:

RhapsodyPowerPack.GenerateAsHTML.MaxContainerWidth

This property (in pixels) governs the default width of the container in the details page (although containers on pages with diagrams or tables auto-expand beyond this value.

RhapsodyPowerPack.GenerateAsHTML.SidebarWidth

The documentation uses Bootstrap which organizes the content over 12 columns. This property sets how many of those columns is occupied by the Sidebar (default 3). The sidebar may be made wider or thinner by setting this property to a different value.

Running From a Command Line

The generation may be invoked as part of a command line by using Rhapsody’s -cmd=call command line switch, for example to run the generation on the project:

C:\IBM\Rhapsody\rhapsody.exe -cmd=open C:\Work\CommandLine\CommandLine.rpyx -cmd=call "GenerateAsHTML"

Optionally you may specify the starting point for the generation by specifying the full path to a model element as an argument (add a space between GenerateAsHTML and the full path argument), for example:

C:\IBM\Rhapsody\rhapsody.exe -cmd=open C:\Work\CommandLine\CommandLine.rpyx -cmd=call "GenerateAsHTML RequirementsAnalysisPkg::RequirementsPkg"

The full path of a model element may be easily obtained using the Get Full Path helper.