Book a Demo
Prev Next

Scriptlets

Scriptlet elements contain JavaScript that lets you tap into the underlying diagram and element API for customizing the element's appearance, text, Tagged Values and other properties on the fly. Scriptlets run whenever the diagram is loaded, or can be run manually on demand, providing diagrams with more than a single static view.

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

For references to Help topics related to these objects see the Learn More links.

Access

Scriptlets can be placed on any diagram. You can place any number of Scriptlets on a  diagram and you can place a given Scriptlet on more than one diagram.

Perspective

Construction > Scriplets

Diagram Toolbox

To create a Scriptlet:

  • Open the Toolbox
  • Select the Scriptlet artifact from the 'Dynamic Viewpoints' page of the diagram toolbox
  • Drag it onto an open diagram

Scriptlet Permissions

Code in Scriptlets cannot alter or update elements in the model database.  It can, however, read and update copies of the elements that are displayed on a diagram. Updates to elements made by Scriptlets are NOT written back into the model database.

Editing Scriptlet Code

To add code to a Scriptlet, or to edit existing code for a Scriptlet, either double-click on the Scriptlet on a diagram, or right-click and select the 'Edit Script' menu option. The Code Editor window opens, showing the code for the selected Scriptlet.  Edit the JavaScript code for the Scriptlet, as you would in any code editor.  Press the Ctrl+S keys to save your changes.

An Example of a Scriptlet

This example comes from the model pattern 'Scriptlets > Simple', available through the Model Builder.

//---   Example Scriptlet  ---
function Scriptlet1()
{
var object as EA.DiagramObject;
object = theDiagram.GetObjectByGrid("A","2");
if(object)
{
Session.Output("Scriptlet1 for " + theDiagram.Name);
object.BackgroundColor = parseInt("0x554444",16);
object.FontColor = parseInt("0xeeeeee",16);
object.Update();
}
}

Scriptlet1();

Running a Scriptlet

Scriptlets are run whenever the diagram containing them is loaded or reloaded, prior to the diagram being displayed. If a diagram contains multiple Scriptlets, the order in which they are run is determined by the Z-order of the Scriptlets on the diagram.  Scriptlets can also be run manually at any time, by right-clicking on the Scriptlet and choosing the option 'Run Script' from the context menu.

Debugging a Scriptlet

You can debug a Scriplet as for any other section of code. Right-click on the Scriptlet and select the 'Debug Script' menu option. The Scriptlet is displayed in the Debug View.

Scriptlets on Grid Style Diagrams

The automation API has some specialized functions that Scriptlets can use when acting on diagrams displayed in a Grid style. 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");

Learn more

Prev Next