Skip to main content

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).

info

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:

NameDescriptionType
_idUnique id for the extension (must be {publisher}.{code}String
publisherThe publisher of the extensionString
codeThe code id of the extensionString
nameThe name of the extensionString
descriptionThe long description of the extension to be shown in the extension catalogString
documentationA URL to some external documentationString
iconThe icon (bootstrap icons) to be shown next the extension name in the catalogString
viewsAn array of views to be shown in the portal or excel add-inExtensionView[]
resourcesA set of resources used by this extension that will be published/installedObject (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.

info

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:

NameDescriptionType
idThe unique identifier for this view in the extensionString
sectionThe section in the menu to display this view, defaults to ExtensionString
nameThe name of the view as shown in the menuString
descriptionA description of the viewString
tabnameThe name of the tab, defaults to 'Main'String
appnameThe name of the view in the Apps catalogue, only used if the tabname is 'Apps'String
excelTrue if this is an Excel Add-in view, defaults to falseBoolean
iconThe icon shown next to the name in the GUIString
featureThe feature policy used to determine if a user can see this viewString
scriptThe mustache script containing the code for this viewString
insightsSet this to true if this app is a new menu item and you want to show an Insights tabBoolean

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.

info

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"