Prev Next

Dynamic Charts

DynamicChart Artifacts are Chart elements for which the series, style and content are managed entirely through the Automation Interfaces by clients - typically plugins and scripts.

The Automation Interface

The Chart interfaces provide clients with the means to dynamically describe and populate a Chart when the diagram is viewed. The API is wide ranging and flexible, allowing you to illustrate various scenarios graphically at runtime.

The best reference for the chart interfaces and their use is the 'EA 15 Examples > Dynamic Charts' Package in the Enterprise Architect Example Model. This Package contains examples of many charts, each described dynamically by JavaScript clients. Each chart example presents two methods of rendering - a JavaScript coding method and a JSON datasource method.

When a diagram that contains one or more DynamicChart Artifacts is opened, the system will execute the behavior associated with each of those elements. This behavior is written in JavaScript, and it must contain an implementation of the ConstructChart method (a JavaScript behavior that you create). This method will be then be invoked, with the GUID of the element passed to it as a parameter.

Dynamic Chart Coding

Dynamic Charts rely completely on code to define their style and content. JavaScript is the primary language for coding charts using automation; however, it is certainly feasible for a third-party automation client to be involved in that process, the JavaScript host delegating tasks to the automation clients in languages such as C# and C++, which might be able to obtain data from outside the model in ways not available to scripts.

The creation process begins by creating a DynamicChart Artifact element, then editing its behavior using the shortcut Alt+7 or the 'Edit Chart Script' context menu option, to display the Code Editor window.

The first thing you need to write is the ConstructChart function, which will be invoked automatically whenever a diagram containing a DynamicChart Artifact is opened for viewing. Within this function, it is entirely up to you what type of chart to display, the style of the chart, the number of series it contains, and the data points that make up the series. Using the Chart Package from the Automation Interface, it is possible to display almost any chart you require using only JavaScript.

The best reference for a coding example is provided in the Example Model ('EA 15 Examples > Dynamic Charts' Package). Each chart example provides a Dashboard diagram and DynamicChart element. Select any of these elements and press Alt+7 to view the behavior code behind the chart. Referring to the numerous examples is the best way to understand how to code each type of chart.

Dynamic Charts Datasources

Rather than code a Dynamic Chart yourself, you might want to provide a simple description of the Chart instead. Dynamic Charts can be designed and entirely defined by a single datasource; JSON is currently the preferred datasource format, but XML and others will be added in the future.

You define the Chart by providing a simple JSON data structure that adheres to the DynamicChart schema. The schema is available in the Schema Composer, and is also easily viewable in the Dynamic Charts Package of the Enterprise Architect Example Model.

To render a chart using a JSON data structure, first select the DynamicChart Artifact element and use Alt+7 or the context menu option to edit the chart script or behavior. When the editor appears,create a JSON variable that defines the chart to render, then compose your ConstructChart function.

The ConstructChart function takes one argument, which is the identity (a GUID string) of the Chart element being displayed on the opening diagram. You then call the built-in function ConstructChartFromJSON, passing the GUID as the first parameter and the JSON structure as the second argument, as illustrated in this example:

var barChart2DJSON =

{

  "Category" : "BarSmart",

  "Type" : "Simple",

  "Title" : "Vehicle Expenses",

  "Series" :

  [

     {

"Label" : "Fuel",

"Data":

{

"Type" : "Column",

"Points" :

[

{ "Category": "Jan", "Y": 1.0 },

{ "Category": "Feb", "Y": 3.0 },

{ "Category": "Mar", "Y": 7.0 },

{ "Category": "Apr", "Y": 8.0 },

{ "Category": "May", "Y": 10.0 },

{ "Category": "Jum", "Y": 15.0 }

]

}

},

{

"Label" : "Taxes",

"Data":

{

"Type" : "Normal",

"Points" :

[

{ "Y":10.0 },

{ "Y":12.0 },

{ "Y":16.0 },

{ "Y":17.0 },

{ "Y":10.0 },

{ "Y":12.0 }

]

}

},

{

"Label" : "Maintenance",

"Data":

{

"Type" : "Normal",

"Points" :

[

{ "Y":5.0 },

{ "Y":2.0 },

{ "Y":6.0 },

{ "Y":7.0 },

{ "Y":1.0 },

{ "Y":2.0 }

]

}

},

{

"Label" : "Other",

"Data":

{

"Type" : "Normal",

"Points" :

[

{ "Y":2.5 },

{ "Y":2.5 },

{ "Y":2.5 },

{ "Y":2.5 },

{ "Y":2.5 },

{ "Y":2.5 }

]

}

}

  ]

};

function ConstructChart(chartGuid)

{

ConstructChartFromJSON(chartGuid, barChart2DJSON);

}

Further JSON examples are provided in the Example Model. Each Chart example provides a Dashboard diagram and DynamicChart element. Select any of these elements and press Alt+7 to view the behavior behind the chart. Looking at the variety of chart examples is the best way to get to know how to use JSON to produce the types of chart you might be interested in.

Learn more