Extension Basics
Introduction
This topic is a brief introduction to getting started building application extensions.
Application extension
An extension comprises a set of components and an extension configuration (manifest).
If you are going to publish your extensions to the public repository, you will need a publisher code. You can apply for one by logging a support request in the support portal.
Configuration
An extension has the following properties:
Name | Description | Type |
---|---|---|
_id | Unique id for the extension (must be {publisher}.{code} | String |
publisher | The publisher of the extension | String |
code | The code id of the extension | String |
name | The name of the extension | String |
description | The long description of the extension to be shown in the extension catalog | String |
documentation | A URL to some external documentation | String |
icon | The icon (bootstrap icons) to be shown next the extension name in the catalog | String |
views | An array of views to be shown in the portal or excel add-in | ExtensionView[] |
resources | A set of resources used by this extension that will be published/installed | Object (See Below) |
Feature policy
In order to see the extension views in your extension, you need to create a feature policy, an example is shown below:
fp = FeaturePolicy()
fp.id = "extension.odsl.example"
fp.description = "Show odsl Example extension views"
fp.features = ["odsl.example.test"]
fp.addMember("*")
fp.deny = false
fp.enabled = true
save fp
The features array must include the feature names added to the views feature property.
For standardisation, it is good practice to name your feature policy as extension.{publisher}.{code}
Name your features as {publisher}.{code}.{viewid} - note you can also use a single feature code for all the views in the extension.
Resources
Extension resources are a list of entities which need to be installed with the extension. Resources are a SimpleObject, with each key in the document being a service name. The value of the service can either be key=values or an array, e.g.
e.resources.script.uninstall = "example-odsl\examples\Extension\odsl.example.uninstall"
e.resources.policy = ["extension.odsl.example"]
Extension views
Extension views are bespoke screens created using Mustache files and displayed in the web portal.
They can be placed in one of the following places:
- A tab in a new menu item
- A new tab in existing menu item
- Special Apps tab in a menu item
The following properties determine where the extension view is placed:
- section - this is the name of the section in the left-side menu, e.g. Manage
- name - this is the name of the menu item in the defined section, e.g. Groups
- tabname - this is the name of the tab to show - if it is Apps, it will be placed as an entry in the special Apps tab
Configuring an extension view
Here are all the fields to define an extension view:
Name | Description | Type |
---|---|---|
id | The unique identifier for this view in the extension | String |
section | The section in the menu to display this view, defaults to Extension | String |
name | The name of the view as shown in the menu | String |
description | A description of the view | String |
tabname | The name of the tab, defaults to 'Main' | String |
appname | The name of the view in the Apps catalogue, only used if the tabname is 'Apps' | String |
excel | True if this is an Excel Add-in view, defaults to false | Boolean |
icon | The icon shown next to the name in the GUI | String |
feature | The feature policy used to determine if a user can see this view | String |
script | The mustache script containing the code for this view | String |
insights | Set this to true if this app is a new menu item and you want to show an Insights tab | Boolean |
HTML Components
We provide a useful set of data-connected HTML components which can be used in your extension views.
Mustache file
The mustache file that provides the view can be created in VSCode and saved to the server using the OpenDataDSL add-in.
The best way to start the mustache file is by including the #odsl-extension script by adding the following line at the top of the file:
{{>#odsl-extension}}
You can then proceed to add the HTML and javascript required for the desired functionality.
Insights
You can create insights and include them in the extension manifest resources, so they will be published/installed.
In order to show the insights on the Insights tab of the extension, set the category on the insight to be the same as the insight id, ie. {published}.{code}
Publishing an extension
If you want to publish your extension into the public repository so other companies that use the OpenDataDSL platform can install and use it, you need to become a publisher.
You can apply to be a publisher by logging a support request in the support portal.
To publish your extension, you need to read the extension from your private repository and publish it to public, e.g.
e = ${extension:"odsl.example"}
publish e to "public"