Prev Next

Grid-Style Diagrams

Grid-style diagrams allow you to manage and organize diagrams, by sorting diagram elements into cells within a grid. The grid functionality integrates with the new scripting API to facilitate setting the appearance of diagram elements dynamically, as the diagram is loaded.

Access

Properties Window

Select 'Enable' from the drop-down list for the option 'Grid-style' under the heading 'Appearance'.

This action turns on the 'grid-style' setting and opens the 'Grid Properties' dialog, where you can specify the Grid settings.

Context Menu

For diagrams that are displayed with Grid-Style enabled, the context menu option 'Grid' offers a number of commands specific to grid-style diagrams.

They are:

  • Show Grid Lines
  • Show Grid Headers
  • Edit Grid
  • Compact Grid

Setting the Grid Style Properties

Enabling 'Grid-Style' on a diagram creates a number of columns on the diagram, according the values specified in the 'Grid Properties' dialog. The rows are laid out dynamically according to the number of columns and the number of elements on the diagram.

The 'Grid Properties' dialog is displayed at the time of enabling grid-style for a diagram.

The dialog can also be displayed at any time after grid-style has been enabled, by selecting the context menu option 'Grid > Edit Grid'.

On the dialog you set a number of properties:

  • The number of columns
  • Whether to show the grid lines
  • Whether to show the column headings
  • The width of the cells
  • The height of the cells
  • How to add new elements to the diagram - if the cell the element is being added to is already occupied, this option determines if the system searches for the first free cell by row (searching left to right/top to bottom) or by column (top  to bottom/left to right)

Altering the Grid Cells Using Scriptlets

Scriptlet artifacts can be used to run JavaScript code to access elements in a grid-style diagram and set the appearance of those elements.  For example, to set the font and background color, or to alter the text that is displayed.

Each Scriptlet has access to three global objects in addition to the standard automation environment. They are:

  • theDiagram - an automation Diagram interface to the diagram on which the Scriptlet resides
  • theElement - an automation Element interface to the Scriptlet artifact itself
  • theInstance - an automation DiagramObject interface to the Scriptlet artifact itself

When a diagram is viewed as a grid, we can use automation functions to retrieve elements at specified grid locations. The location format is the same as one sees in a spreadsheet, with columns labeled 'A', 'B', 'C', ..., 'AA', 'AB', etc. and the rows numbered in sequence.

To alter the appearance of a grid element, retrieve its underlying Object, using the function GetObjectByGrid.

To alter the value of a grid element, retrieve its underlying Element, using the function GetElementByGrid.

For example;

object = theDiagram.GetObjectByGrid("A", "2");

element = theDiagram.GetElementByGrid("A", "2");

A diagram can contain any number of Scriptlet artifacts.  The Scriptlets will run before the diagram is displayed, and whenever the diagram is reloaded.  When there are multiple Scriptlets on a diagram, the order in which they are executed is determined by their Z-order on the diagram.

Learn more