Diagram Information Box Creator

Overview

This helper adds diagram information boxes to diagrams and keeps them updated.

Applicable To	Package, Project, Any Diagram
Menu Entry	Power Pack  Diagram Tools  Add / Update Diagram Information Box(es)
Demonstration	Watch the Video

Operation

This helper adds Diagram Information Boxes to diagrams or updates existing ones.

Diagram Information Boxes are formatted new-term comments with the following tags:

· createdBy

· creationdate

· lastModifiedBy

· lastModifiedOn

Diagram Information Box Stereotype

Diagram Information Box

The createdBy and lastModifiedBy tags are populated based on the currently logged-in Windows username.

The creationDate tag is the date/time that the Diagram Information Box was created.

Launching the Diagram Information Box Creator

There are three ways in which the helper may be triggered to run:

· Manually.

· Automatically on project save.

· Automatically after diagram creation.

Manually Launching

The helper may be manually launched on a single diagram, on a package or on a project. If launched from a diagram, then a new Diagram Information Box is created (owned by the diagram) and added to the diagram graphics (see below). If the helper is launched from a project / package, then new Diagram Information Boxes are created for all diagrams in that package / project. This is filtered using the following properties (which by default are all set to false to prevent the creation of potentially unwanted boxes). Note that these are Rhapsody base types but also affect any new terms based upon them.

RhapsodyPowerPack.DiagramInformation.AddToActivityDiagrams

RhapsodyPowerPack.DiagramInformation.AddToCommunicationDiagrams

RhapsodyPowerPack.DiagramInformation.AddToComponentDiagrams

RhapsodyPowerPack.DiagramInformation.AddToDeploymentDiagrams

RhapsodyPowerPack.DiagramInformation.AddToObjectModelDiagrams

RhapsodyPowerPack.DiagramInformation.AddToPanelDiagrams

RhapsodyPowerPack.DiagramInformation.AddToSequenceDiagrams

RhapsodyPowerPack.DiagramInformation.AddToStatechartDiagrams

RhapsodyPowerPack.DiagramInformation.AddToStructureDiagrams

RhapsodyPowerPack.DiagramInformation.AddToUseCaseDiagrams

These properties are also used by the automatic invocation described below.

After Diagram Creation

When a new diagram is created, the helper first checks if the project level property below is set to true (this is for performance reasons since Rhapsody’s After Add Element API trigger will happen every time a new model element is created).

RhapsodyPowerPack.DiagramInformation.TriggerOnNewElements

If this property is set to true, then the helper checks for one of the above properties on the owning package based on the type of diagram being created. If the property is true then the helper runs on that diagram as if it were manually invoked, creating a new Diagram Information Box.

On Project Save

Whenever the project is saved, the helper first checks if the project level property below is set to true (this is for performance reasons since Rhapsody’s Before Project Save API trigger will happen every time a model is saved).

RhapsodyPowerPack.DiagramInformation.TriggerOnProjectSave

If this property is true, then the helper iterates over every existing Diagram Information Box in the model and updates:

· The content of the box.

· Its position on its diagram (provided it is already on the diagram and the relevant AutoMove property is true – see below)

No new boxes are ever created on save.

No boxes are added to diagrams on save.

Configuring the Diagram Boxes

Diagram Information Box Formatting

The date / time format used for the createdOn and lastModifedOn tags may be controlled using the following properties:

RhapsodyPowerPack.DiagramInformation.DisplayFormatCreationDate

RhapsodyPowerPack.DiagramInformation.DisplayFormatLastModifiedOn

These properties use the following keywords:

· dd = day

· MM = month

· yyyy = year

· HH = hour

· mm = minute

· ss = second (whilst it is unlikely anyone would want seconds displayed in a production environment, they are useful for testing purposes)

The default setting is dd/MM/yyyy - HH:mm

Diagram Information Box Position

The positions of Diagram Information Boxes are controlled by the following properties (which may be set on a specific diagram or at package / project level).

· Activity_diagram.DiagramInformation.Position

· ObjectModelGe.DiagramInformation.Position

· SequenceDiagram.DiagramInformation.Position

· StatechartDiagram.DiagramInformation.Position

· StructureDiagram.DiagramInformation.Position

· UseCaseGe.DiagramInformation.Position

This position may be set to Bottom Right, Bottom Left, Top Right or Top Left and is either:

· Relative to the diagram frame*

· Relative to the corner-most element on the diagram (for UML-based models where diagrams do not have a frame at all).

o If the diagram is empty, then the box is placed at the top-left hand corner (well almost – even if the helper asks for the element to be placed at 0,0 Rhapsody usually places it indented)

*SysML-based diagrams exhibit some strange behavior. On creation, if the diagram frame is toggled off (because the property General.Graphics.ShowDiagramFrame was set to false) then the diagram has no frame at all – just as if it were created in a UML-based model. If you toggle it on by right-clicking the diagram background and selecting Show/Hide Diagram Frame – from that point on the diagram has a frame. Even if you toggle if off again – the API reports the diagram has a frame and there is no way to detect whether it is visible.

This means that when you add / update a box using the helper, SysML-based diagrams which have never had their frame toggled on are treated as if they were UML-based diagrams but if you toggle the frame on then they are treated as SysML-based ones.

Note: For existing Diagram Information Boxes, a position property change only takes effect if the corresponding property below is set to true. This may be set on a diagram or at package/project level. By default, these properties are set to false to prevent a box being moved if a user has manually moved it to where they want it to be:

· Activity_diagram.DiagramInformation.AutoMove

· ObjectModelGe.DiagramInformation.AutoMove

· SequenceDiagram.DiagramInformation.AutoMove

· StatechartDiagram.DiagramInformation.AutoMove

· StructureDiagram.DiagramInformation.AutoMove

· UseCaseGe.DiagramInformation.AutoMove

The following property defines a margin between the Diagram Information Box and the existing corner model element / frame on the diagram:

RhapsodyPowerPack.DiagramInformation.Margin

Diagram Information Box Size

The height of the box is automatically calculated based on the number of tags it has.

The width of the box is set using the property:

RhapsodyPowerPack.DiagramInformation.DefaultWidth

Note that for existing boxes, if the user has manually resized the box then the new width is used to calculate position relative to other elements instead of the default.

Customizing and Extending the Diagram Information Box Creator

Instead of the supplied Diagram Information Box, you may supply your own new term stereotype (applicable to Comment). The helper displays all tags found in the new term stereotype so if you only wanted two of the out of the box tags (for example) then copy only the two you want into the replacement stereotype. New tags may also be added (see below).

To instruct the helper to use the new stereotype rather than its own, set the following property on the project or on a package (different packages may then use different custom boxes if desired):

RhapsodyPowerPack.DiagramInformation.CustomDiagramInformationStereotype

The property should contain a string which is the full path to your stereotype, in the following format (note the project is not required in the path):

Package::Package::Package::Stereotype

for example:

MyProfile::Stereotypes::MyStereotype

Adding New Diagram Information Tags

To add additional diagram information, add tags to the new stereotype and then provide a plugin to update them. If the following property is set (on the owning package or project) then after the helper has performed its own updates, it calls the menu entry specified:

RhapsodyPowerPack.DiagramInformation.PostProcessPlugin

The property should contain a string that is the exact menu entry from your hep file, for example:

Your Toolkit\Update Diagram Information

If specifying the same in a property (.prp) file be sure to use double-slashes (Rhapsody will remove the first instance of each when it reads the property file), for example:

Your Toolkit\\Update Diagram Information

Sample Model

The sample model (Samples/DiagramInformation) includes an example of using custom information. The sample has the following elements:

A profile that defines a custom Diagram Information box:

A sample package where properties have been set:

An eclipse project that sets the classification tag on any diagram in the CustomBoxes package to the current value of the Classification tag on the package:

You can test it by changing the value of the package level tag and then click save – the diagrams in the package should update: