Model-Based Add-ins are a relatively new feature in Sparx Systems Enterprise Architect (EA). This article provides:
- An overview of Model-Based Add-ins and how they differ from scripts.
- The characteristics of Model-Based Add-ins.
- A suggested workflow for the development of a Model-Based Add-in.
- A simple example.
A Model-Based Add-in is a stereotyped UML Class element with JavaScript code set as the behaviour for operations defined in that class. They differ from scripts in the following ways:
- A Model-Based Add-in must be coded in JavaScript whereas a script can be coded in either VBScript, JScript or JavaScript.
- The code for a Model-Based Add-in is stored within a UML Class element, whereas the code for a script or (scripts) is / are stored in the model repository.
- A Model-Based Add-in can be executed from a menu in the Specialize ribbon, and / or respond to events raised by EA. Scripts, are executed by the EA user.
The events raised by EA and which can be responded to are as shown below:
These event categories are:
- Add-in Events – required for all Model-Based Add-ins that are required to respond to a menu within the Specialize ribbon.
- Broadcast Events – The most and plentiful of events which are broadcast by EA when something happens within EA. For example, an element is added, modified or deleted.
- MDG Events – specialised events broadcast when EA interacts with an MDG technology.
- Workflow Events – legacy events from an earlier version of EA (version 9 I believe) which introduced the concept of a workflow. This was supposed to be able to restrict users to what properties of an element they could modify, however, the set of properties defined was very small and not the properties that are used most frequently. These events are rarely, if ever, used.
Full details of all of the events list above, the full event signature and explanation of the event can be found at:
Enterprise Architect Add-In Model | Enterprise Architect User Guide (sparxsystems.com)
Click on the specific event category from the links on the left-hand side of the page above.
The following is a summary of the characteristics / limitations of Model-based Add-ins:
- To enable the use of Model-based Add-ins, the MDG Technology Model Add-Ins must be present in your active EA Perspective.
- Model-based Add-ins are implemented as a <<JavascriptAddin>> stereotyped UML class element.
- The responses to EA events are implemented using JavaScript code within <<reception>> operations.
- Code can be encapsulated inside operations which can call each other and can be called from the <<reception>> operations.
- Data constants and variables global to all operations are defined as attributes.
- You cannot use libraries of code via !INC statements.
- User input/ output is limited to model dialogs and the System Output window using:
- Session.Input – model dialog.
- Session.Output – System Output Window.
- Session.Prompt – model dialog.
- Code complete whilst entering code for the operations is partially enabled.
- Results / output can be displayed using:
- System Output Window.
- Model Addin Window.
- Seatch Window.
Sparx Systems does provide working examples of Model-based Add-ins in the EAExample.qea model repository accessed via the Help menu in the Home ribbon of the EA workspace.
The following flow is a suggested workflow for the development of Model-based Add-ins:
The following are basic steps that you can follow to develop a very simple Model-based Add-in that uses an Add-in menu to display Hello World! in a model dialog.
To keep this article short, no screen shots are provided here and a working knowledge of EA v 16.x is assumed:
- Ensure Code Engineering toolbar is visible in workspace.
- Create a new, or add to an existing Perspective:
- Basic UML.
- Class Modeling.
- Model Add-Ins.
- Set this to be the Active Perspective.
- Make the System Output window visible.
- Create a new qea based repository named Model-Based Add-in Test.
- Add a new View with a UML Class Diagram.
- Import to the Model Root the Broadcast Types using Create from Pattern. NOTE: you can select which set of events you wish to import.
- Set Code Engineering to JavaScript.
- Add a UML Class named HelloWorld to the diagram.
- Change its stereotype to JavascriptAddin using the element Properties window.
- Drag and drop the following broadcasts from the package Add-in Events to the class created earlier:
- EA_Connect
- EA_GetMenuItems
- EA_MenuClick
- Set the Diagram Properties to show Full Details for Operations.
- Add the following Attributes (no types) to the class:
- version default value “1.0”
- promptOK default value 1
- Add an Operation named ShowAbout():void to the class.
- Add the following code to this operation using Develop → Behavior → Edit Internal Code.
Session.Prompt("Hello World!\n\n" +
"Author : Phil Chudley - September 2023\n\n" +
"Version : " + this.version, this.promptOK);
// You may, of course, use your own name here.
- Add the following code to the receptions:
EA_Connect
return "";
EA_GetMenuItems
if (MenuName == "-Demo")
{
return "Hello World!"; //Only sub-item for menu
}
else
{
return "-Demo";
}
EA_MenuClick
if (ItemName == "Hello World!")
{
this.ShowAbout(); // Display the About modal dialog
}
- Save the Diagram.
- Activate the Model Based Add-in by selecting Specialize → Manage Addin and checking Optional.
- If the AddIn appears in the ribbon, select Hello World! From the menu and verify the dialog is displayed. NOTE this is in the Task Bar upon first activation.
- If the Addin does not appear:
- Examine the System Output window tab named Demo to view the errors.
- Correct the errors.
- Attempt to activate the Add-In again by selecting Specialize → Manage Addin and checking Optional.
We hope that you have found this article useful, and you should now be able to begin the task of developing Model-Based Add-ins for yourself.
There are many uses for such Model-Based Add-ins, including one that Dunstan Thomas developed recently. This was to detect and report for any element whose name was the same as any other element with the same type and stereotype, thus mitigating the issue of duplicate element names.
Use the button below if you would like to engage us for Model-Based Add-in development: