Book a Demo

Please note : This help page is not for the latest version of Enterprise Architect. The latest help can be found here.

Prev Next

Use of the Help System Elements

This topic explains how to set up each type of Help element so that it is generated as a functional and useful component of the Help page.

It is assumed that you have read the Help topic Help System Authoring and are aware of what elements are available and how they fit into the Help page structure.

Set up the Help Page

There are two quick ways to set up a structure for a new Help topic.

Model Patterns

Open the Model Wizard (Start Page, 'Create from Pattern' tab), click on the icon and select the Help Profile.

Review the patterns listed in the left-hand panel, select the most appropriate for your Help page, and click on the Create Model(s) button.

Drag from the Diagram Toolbox Help System page onto the Browser window

  1. Select the Package/Help Package to contain this topic.
  2. Drag the HelpPackage icon from the Toolbox onto the selected Package in the Browser, and in the 'New Package' dialog give the new HelpPackage a name.
  3. Drag the HelpTopic or HelpTopicProxy icon from the Toolbox onto the new HelpPackage in the Browser.
  4. Drag the appropriate HelpSection, HelpTablexn or other Help element icon from the Toolbox onto the HelpTopic in the Browser. Repeat this as often as you require.
  5. If you have added any HelpTables, drag the HelpTableRow icon from the Toolbox onto the appropriate HelpTable in the Browser.
  6. Finally, if required, drag the HelpSectionLearnMore icon from the Toolbox onto the Browser window, and position it at the end of the set of elements.

Having set up the structure, you can then add the contents and set any Tagged Values and properties that might be required. You can use the Notes window on each Help element to add the text, and the Properties window to set the properties. The Notes window gives you a quick and flexible means of writing and formatting text.

Whilst you can use the Notes window alone to begin with, it is far better to use it in conjunction with the Specification Manager, which allows you to see the structure and content of the Help page as you create it.

The Specification Manager is also the best tool to add further Help elements to the topic as it develops, dragging the appropriate icon from the Toolbox Help System page onto the preceding or parent element in the Specification Manager. You are prompted to select whether the new element comes after the existing element as a peer, or under the existing element as a child.

Creating Help Elements

Each Help element is a Class element modified by a stereotype. If you happen to drag the wrong Help element into a Help structure, or you change your mind about how to present your information, you can change the stereotype of the existing element to make it the correct element type. To do this:

  1. Click on the element and then go to the Properties window for the element.
  2. In the 'Stereotype' field, click on the Browse. icon and, in the 'Stereotype for element name' dialog, scroll up or down the list to locate the required stereotype, and select the checkbox against it.
  3. Click on the OK button.
  4. Click on the Browse. icon in the 'Stereotype' field again and clear the checkbox against the incorrect stereotype.
  5. Click on the OK button.

Note that by adding the correct stereotype before deleting the incorrect stereotype, you should retain the values in any Tagged Values that are common to both stereotypes (such as column headings), avoiding the need to reset the values.

Remember that Tagged Values allocated to stereotypes by profiles are listed on the 'Element' tab of the Properties window, not on the 'Tags' tab.

HelpPackage

Each topic in the Help System is represented by a HelpPackage containing a HelpTopic child element of the same name.

HelpPackages are arranged in a hierarchy of parent and child Packages to develop the structure of Help pages in the Help system.  This package hierarchy is then reflected in the generated webpages, through a breadcrumb control at the top of the page and a menu like list of links to child topics on the left of the page.

Note that the top-level packages in a Help hierarchy (effectively the 'Chapter' nodes; for example, in Enterprise Architect's own Help, 'Modeling Languages') should have the code engineering 'Namespace Root' flag set.  When generating Web Help, Enterprise Architect creates sub-folders within the specified output folder, using the names of the Namespace Root packages as the folder names.  Each generated topic file is placed in the sub-folder created from its nearest parent package that is marked as a Namespace Root.  As a minimum, a single top-level package must be marked as a Namespace Root.  The Namespace Root can be set by clicking on a Package then selecting the 'Develop > Source Code > Options > Set Package as Namespace Root' ribbon option.

The HelpPackage is not directly generated as Help, but rather acts as the container for the HelpTopic and its own child elements. It is important that the Help Package and Help Topic element share the same name.

HelpTopic

A HelpTopic element corresponds to an HTML page.

It is important that the HelpTopic 'Alias' property is set to the required filename for the Help topic in the final generated output. The Alias must have a unique name within the whole Help System and should not include the extension. For example 'requirements_management' (without quotes) is a valid Alias and will provide the filename 'requirements_management.html' when generated.

The HelpTopic element usually contains some introductory text (in the element 'Notes' field) to explain the purpose of the topic and how it fits into any topic structure of which it is a part.

There can only be one HelpTopic element in a Package. The HelpTopic can be the parent of most other Help elements, except for HelpTopicProxy, HelpTableRow and HelpTableRowProxy.

HelpTopicProxy

A HelpTopicProxy element captures the content of an existing HelpTopic element and its child elements, and duplicates them under another HelpPackage. You therefore insert the HelpTopicProxy element as a child of the HelpPackage.

You give the HelpTopicProxy its own topic name and appropriate Alias. In the Properties window for the element, for the 'refTopic' Tagged Value, you click on the Browse. icon and locate and select the HelpTopic to duplicate.

You do not need to do anything else in the HelpTopicProxy or the HelpPackage elements.

HelpSection

A HelpSection element corresponds to one or more related paragraphs within a page, discussing a particular subject. The HelpSection name will appear as a heading and the element notes as the content.

A HelpSection can only be a child of a HelpTopic, and cannot contain any other element.

If you have more than one HelpSection element under a topic, they will appear in the generated page in the order they appear in the Browser window and Specification Manager. You can embed links to diagrams and screen shots within the HelpSection content, and these will be reproduced in the web or PDF content as required.

A HelpSection element with the name 'Notes' is usually placed second-to-last in the HelpTopic (before the 'Learn More' section, if present), containing a bullet list of additional points about the subject of the topic, such as which Enterprise Architect or DBMS permissions might be required to perform a task.

HelpSectionProxy

Similar to the HelpTopicProxy, a HelpSectionProxy duplicates the content of an existing HelpSection. You insert the HelpSectionProxy as a child of the HelpTopic element, in the appropriate position in the sequence of peer HelpSection, HelpSectionProxy, HelpTable and HelpTableProxy elements under the HelpTopic.

The HelpSectionProxy has its own element name. In the Properties window for the element, for the 'refSection' Tagged Value, you click on the Browse. icon and locate and select the HelpSection to duplicate.

HelpSectionDiagram

A HelpSectionDiagram element is used as a placeholder/container for a diagram that will appear in the Help as an image.

The diagram should be built below the HelpSectionDiagram element; any elements or constructs that appear in the diagram will not appear in the HTML, Web or PDF documents themselves. This allows for the creation of explanatory diagrams without the burden of fitting each represented element into the Help document itself. The elements in the diagram will, however, be listed in the Browser window and the Specification Manager.

You can include text in this element. As the diagram is essentially subordinate to the HelpSectionDiagram element, the text belonging to element will display above the diagram.

Apart from providing a name for the HelpSectionDiagram element you do not have to set any properties.

This element is generally used for stand-alone diagrams that illustrate general features or concepts. If a diagram or image is an example of a point explained in a HelpTopic, HelpSection or HelpTableRow, you have hyperlink mechanisms in the text for linking to that diagram or image held elsewhere in the model or in the Image Manager.

HelpSystemVideo

A HelpSystemVideo element is a container for a video control, which will play a video within the web browser in which the Help is being viewed. This allows for the inclusion of short 'How To' videos from your website, which can be initiated from within the online Help.

After providing a name for the element, you set up this facility by completing this set of Tagged Values.

  • VideoTitle - Type in a title or label for the video
  • VideoURL - Click on the Browse. icon and locate and select the url to play the video; the URL can be an absolute or a relative value, it is inserted into generated document without modification
  • VideoType - Type in the type of file; for example, video/mp4
  • Duration - Type in the time the video takes to play, in seconds
  • ThumbnailURL - Type in the location of the icon that represents the video;  the URL can be an absolute or a relative value, it is inserted into generated document without modification

Note that the Duration and ThumbnailURL values are not included in generated HTML or PDF docuements, they (along with the other values) are written into the 'site-map.xml' file, which is used to improve the search rankings of your website files.

HelpSlideshow

Similar to the HelpSystemVideo element, the HelpSlideshow element enables the user to run a slide show of static screens depicting stages in a process, or examples of output, or other images illustrating the subject of the Help topic. Again, you provide a name for the element, and complete these Tagged Values:

  • Icon - click on the Browse. icon and locate and select the image from the Image Manager on which the user will click to start the slide show; this image could be a standard for all your slide shows
  • Image1 - click on the Browse. icon and locate and select the image from the Image Manager that represents the LAST slide to be shown; see the explanation below this list
  • DiagramRef - To Be Defined

The HelpSlideshow definition includes the Tagged Value 'Image1'. If you intend to have a slideshow of more than one image, you go to the 'Tags' tab of the Properties window and create further Tagged Values there. You have two options:

  1. Create as many additional 'Image1' Tagged Values as you require, without limit. Each new Tagged Value is added to the top of the list and, all being of the same name, they will be acted on in the sequence top to bottom, so perhaps just add the Tagged Values first and add the slide images in the required sequence when you have finished.
    As these are all 'Image1' Tagged Values and part of the definition, they will appear in the 'Element' tab in the stereotype Tagged Values section, in the order newest to oldest (if they don't, click off the element and click back onto it again).
  2. Create up to four Tagged Values of the type HelpSystem::Image2 through to HelpSystem::Image5. Add the first image in your slideshow to the 'Image2' Tagged Value, and the next to 'Image3', and so on. These Tagged Values are part of the HelpSystem profile but not part of the HelpSlideshow stereotype definition, so they are listed in the 'Tags' tab of the Properties window. All Tagged Values are processed by tag name in alphanumerical order, so the HelpSlideshow tags will be processed from 'HelpSystem::Image2' through 'HelpSystem::Image5' to 'Icon' to 'Image1'.

This is why the initial Image1 Tagged Value provided by default when the element is created always contains the last slide in the slideshow - it is the oldest and the last in alphanumerical order.

HelpTable

HelpTable elements come in a variety of formats, depending on the stereotype assigned.

Column names are applied using Tagged Values in the Properties window. In three-column tables the third column contains hyperlinks to other Help topics (set in the HelpTableRow elements), and its heading defaults to 'See also' in the Help generator. Note that 'See also' columns are not reproduced in PDF output generated from the Help source.

A HelpTable element can only be a child of a HelpTopic element, and can only contain HelpTableRow or HelpTableRowProxy child elements.

A complete list of table formats and their stereotypes is provided in the Help System Tables topic.

HelpTableProxy

A HelpTableProxy duplicates the content and definition of an existing HelpTable in a different Help topic, of any style and format. This includes all HelpTableRow and HelpTableRowProxy elements the existing HelpTable might have. The HelpTableProxy element can only be the child of a HelpTopic and cannot have any child elements itself.

After you give the element a name, in the Properties window for the element select the 'refTable' Tagged Value, click on the Browse. icon and locate and select the HelpTable that you want to duplicate in the current topic.

HelpTableRow

A Help Table Row element represents a single row in a table. Generally, the element name becomes the row title, and the Notes field becomes the row description. However, the element has various Tagged Values defined in the Properties window that support different types of row header and column content. These are:

  • ImageRef - you can replace the row header text with an image, in which case you use the image name in the Image Manager as the element name; click on the Browse. icon and locate and select the image from the Image Manager
    If you want to have a row title and an image, give the HelpTableRow element that title as its name
  • Lytebox - To Be Defined
  • ImageArtifact - if you want to add an image held in an Image Artifact to the row, or replace the row title with that image (using the same principles as for ImageRef), click on the Browse. icon and locate and select the image from your file browser
  • ImageLink - click on the Browse. icon and locate and select the Help topic that is displayed when the user clicks on the image
  • SeeAlso - enables you to add a link to another Help topic, the name of which will display in the See also column (where appropriate to the table type)
    Note that these links can only be to HelpTopic elements, not to any other type of object; if you need to link to a website or other URL, create the link in the second column, using the Notes field

HelpTableRows are generated in the table in the same sequence as they are listed in the Browser window. 

HelpTableRowProxy

A HelpTableRowProxy element duplicates the content of an existing HelpTableRow element elsewhere in the model. It has no content of its own. As for the other Proxy elements, after you give the element a name, in the Properties window for the element select the 'refTableRow' Tagged Value, click on the Browse. icon and locate and select the HelpTableRow that you want to duplicate in the current table.

HelpSectionLearnMore

The HelpSectionLearnMore element is used to provide a list of hyperlinks to related topics that have not been linked elsewhere in the topic, nor in the Help hierarchy displayed next to the generated Help topic. It is usually placed last in the HelpTopic so as not to distract from the material presented in the HelpTopic body; however, if there is a lot of content, such as long tables of parameters, attributes or methods, the Learn More section can be inserted above such material, closer to the start of the Help page.

Within the Enterprise Architect Help the section usually consists of a simple bulleted list of hyperlinks to other Help topics or to web sites of relevance. However, you can add explanatory text if necessary, or omit the section if there are no points of reference beyond those already linked to in the rest of the topic.

The PDF generator ignores this element, so the list of links does not display in a PDF document.

HelpPackage Tagged Values for PDF Generation

In the Properties window for a HelpPackage you will see the following list of properties:

  • ReportAlias
  • ReportAuthor
  • ReportCoverImage
  • ReportKeywords
  • ReportProducer
  • ReportStatus
  • ReportSubject
  • ReportSummary
  • ReportTitle
  • ReportVersion

The properties are stored as tagged values, belonging to the stereotype <<HelpPackage>>.

These properties, as well as some standard element properties, are collectively referred to as Report Constants.  The Report Constants (when present) are used when generating PDF documents from your Help model.

From the properties listed above, ReportAuthor, ReportCoverImage, ReportKeywords, ReportStatus, ReportSummary, ReportTitle and ReportVersion, are available for inclusion in your generated documents.   These properties, along with several standard element properties can be inserted as fields into your document templates.  They appear under the 'Report Constants' menu when you right-click in the template editor.  Typically, they would be used in a CoverPage template, or in the header and footer sections of the main document template.

Some of these properties have names similar to standard element properties.  They are: Name, Alias, Keywords, Status and Version.  If the values of any of these stereotype properties are empty, the document fields will use the corresponding standard element property values in their place.

A second and slightly smaller list of properties: ReportAuthor, ReportKeywords, ReportProducer, ReportSubject, ReportTitle, is used to write out metadata for the generated PDF file.

The tagged values from the 'root package' selected for PDF generation, will be used for the entire document.  If the selected package also includes a series of child packages, the tagged values from the child packages are not used as those topics are rendered.

Prev Next