Documentation:Plugins in Turnkey

Plugins in Turnkey

This page was created by Alexandra on 2017-03-26. Last edited by Wikiadmin on 2026-07-29.

You can integrate a JavaScript library into an MDriven Turnkey application when you need a client-side control that the generated UI does not provide, such as a diagram or chart.

A Turnkey plugin in this context is client-side code and its supporting files that you add to a Turnkey application. It is different from a Modlr plugin, which extends modeling and design-time behavior in MDriven Designer or MDriven for Visual Studio.

Choose the integration approach

Use EXT Components for the current, simplified approach to adding reusable components to Turnkey. The video-based asset-folder workflow below remains useful for understanding how a JavaScript library, a ViewModel, an Angular UI override, and a controller work together.

Need	Use	Example
Add a reusable Turnkey client component	EXT Components	Package a component used by more than one view.
Render a JavaScript library in one custom view	A UI override, client assets, and controller code	Draw a diagram from a list of X and Y coordinates.
Add menus, code-generation callbacks, or custom OCL operations at design time	Modlr plugin	Make the OCL editor recognize a custom operation.

How a Turnkey JavaScript integration works

A custom control has four parts:

The library files.: Add the JavaScript library and any required supporting files to the application's deployed assets.
A ViewModel contract.: Expose the data that the library needs through a ViewModel.
A UI override.: Replace or supplement generated rendering with HTML that provides the library's host element.
A controller.: Read the ViewModel data on the client, convert it to the library's expected format, and redraw after Turnkey has processed a server message.

For example, a diagram component can receive a ViewModel collection called DiagramPoints. Each item exposes Xaxis and Yaxis. The controller converts each item to the object format required by the diagram library and passes the resulting array to the library's plot function.

Add a JavaScript library to the application

The legacy asset-folder workflow packages files with the model upload.

Save the model in expanded format when you want the model files to be visible as XML files in a folder. This format is useful when a team manages the model in Git or Subversion.
Locate the asset folder associated with the model. In the demonstrated workflow, the folder has the same name as the Eco model file and ends in _AssetsTK.
Under that folder, add the library files in a folder structure that identifies them as plugin assets. The demonstrated example places the diagram library under content/assets/plugins/flot.
Keep the library's required license material with the library when its license requires it.
Upload the application. Turnkey packages the contents of the _AssetsTK folder and expands them where the application runs, so the files become available to the application.

Do not treat the folder name from the example as a required name for every library. Use a stable, clear folder structure and make the paths used by your UI override match the files you deploy.

Expose data through a ViewModel

Create a ViewModel that gives the client code the data shape it expects. The model does not need to match a library sample model; the important requirement is a consistent contract between the ViewModel and the controller.

For a diagram, expose a collection named DiagramPoints and give its ViewModel class these attributes:

ViewModel member	Purpose	Example value
`DiagramPoints`	Collection read by the client controller	Three point items
`Xaxis`	Horizontal coordinate on each point item	`4`
`Yaxis`	Vertical coordinate on each point item	`12`

When the user creates, deletes, or edits a point, Turnkey updates the ViewModel data. The custom control must then read the updated client-side model and redraw itself.

Inspect the client-side data

Use the application's /debug route while developing to inspect the data sent to the client. Confirm that DiagramPoints exists and that each item contains the expected Xaxis and Yaxis values before troubleshooting the library rendering.

Create the custom rendering

Configure the relevant view for Angular UI rendering and add a UI override that contains the host element for the library. The video example uses an Angular UI tag value on the view and supplies custom HTML for the diagram.

Your override needs an element that the library can find. For example, the markup can provide a dedicated diagram container; the controller then locates that container and asks the library to render into it. Keep the ViewModel names and the controller's lookup names consistent.

Refresh the control after data changes

Turnkey exchanges data with the server through server messages. In the demonstrated integration, the controller refreshes the diagram when processing of a server message is complete:

Handle the client notification that server-message processing has completed.
Read the current DiagramPoints collection from the ViewModel root.
Create a new array for the library.
Iterate over the ViewModel items and map Xaxis and Yaxis to the coordinate properties expected by the library.
Call the library's render or plot function with the mapped data.

The following is pseudocode that illustrates the data mapping; replace the library-specific calls and property names with those required by the library you use.

function refreshDiagram(viewModelRoot) {
  var points = [];

  viewModelRoot.DiagramPoints.forEach(function (point) {
    points.push({ x: point.Xaxis, y: point.Yaxis });
  });

  renderDiagram(points);
}

onProcessingServerMessageComplete(function () {
  refreshDiagram(getViewModelRoot());
});

The refresh point matters. Rendering only when the page first loads leaves the diagram stale after a user changes a row in a grid. Rendering after server-message processing reads the updated ViewModel and makes the diagram reflect creates, deletes, and edits.

Make the integration reusable

Build the controller around a stable ViewModel contract rather than around one specific business model. For example, any view that exposes DiagramPoints with Xaxis and Yaxis can use the same diagram controller, even if the underlying model represents measurements, sales figures, or locations.

Document the contract alongside the component:

Required collection name.
Required attributes and their data types.
Required UI host element.
When the component refreshes.
Any library files and license obligations.

This avoids duplicating library-integration code for each ViewModel.

Develop locally

Use a local Turnkey Core application to shorten the edit-and-test cycle. Turnkey local development tips describes using Windows symbolic links when source folders for CSS or EXT_Components must be available inside the Turnkey Core file tree.

Contents