Extending Clients with Plug-ins
- Technische Redaktion
The features documented here will be part of yuuvis® Momentum 2.4 (2020 Winter) as a Beta implementation. Take care because parts may be changed until the release in the next version!
This article is for developers who want to extend the client with additional functions without the necessity of building a custom client.
Table of Contents
Introduction
The way to extend the reference client, as well as all custom clients based on the core and framework libraries, is simple: put your HTML code into one configuration file and import it. No rebuilding and deployment is necessary. The client loads the new codes dynamically. We will explain how you can extend the client with additional functions in this easy and simple way.
Structure of the Configuration File
The configuration file is in JSON format. The disabled key controls whether the client will use the defined plug-ins or not. In the translations section, you can configure all keys for GUI elements for each language in use. The other sections are described below.
{
"disabled": false,
"links": [],
"states": [],
"actions": [],
"extensions": [],
"triggers": [],
"translations": {
"en": {},
"de": {}
}
}
Plug-in Links
Configured links with a path and label can be hooked into the main menu or the settings menu. The label must be configured in the translations section as shown below.
{
"links": [
{
"id": "yuv.custom.link.home_yuuvis",
"label": "yuv.custom.action.home_yuuvis.label",
"path": "https://help.optimal-systems.com/yuuvis/home_yuuvis_en.html",
"matchHook": "yuv-sidebar-navigation|yuv-sidebar-settings"
}
]
}
Plug-in States
States are new views with their own URL that are mostly reached by clicking a main menu item (see Extend Links). The following example shows how to integrate the user management view of yuuvis® architect as a new view into the client. This view can be opened via a new main menu item 'User management'. This item is offered if the user has the YUUVIS_TENANT_ADMIN role.
{
"states": [
{
"id": "yuv.custom.state.architect.users",
"label": "yuv.custom.state.architect.users",
"path": "architect/users",
"matchHook": "yuv-sidebar-navigation",
"canActivate": "(currentRoute, currentState) => {return this.session.getUser().authorities.includes('YUUVIS_TENANT_ADMIN');}",
"canDeactivate": "(component, currentRoute, currentState, nextState) => true",
"plugin": {
"src": "https://kolibri.enaioci.net/architect/users",
"html": "<style>iframe[src=\"https://kolibri.enaioci.net/architect/users\"] {display: block; height: calc(100% + 50px); margin-top: -50px;}</style>"
}
}
],
"translations": {
"en": {
"yuv.custom.state.architect.users": "User management"
},
"de": {
"yuv.custom.state.architect.users": "Benutzermanagement"
}
}
}
Plug-in Actions
In general, object actions that are listed in the actions menu process specific functions that manipulate the focused object, e.g., Download, Manage follow-ups, Open versions, ... The following example shows TODO.
{
"actions": [ {
"id": "yuv.custom.action.home_yuuvis.list",
"label": "yuv.custom.action.home_yuuvis.list",
"description": "yuv.custom.action.home_yuuvis.description",
"icon": "",
"isExecutable": "(item) => item.id",
"header": "yuv.custom.action.home_yuuvis.label",
"subActionComponents": [
{
"id": "yuv.custom.action.home_yuuvis.sub.simple",
"label": "yuv.custom.action.home_yuuvis.simple",
"description": "yuv.custom.action.home_yuuvis.description",
"priority": 0,
"icon": "",
"group": "common",
"range": "MULTI_SELECT",
"isExecutable": "(item) => item.id",
"run": "(selection) => this.router.navigate(['dashboard'])"
}]
}
]
}
Plug-in Extensions
The standard aspects of the object details offer general views of the data of the object: Overview of all metadata, edit the custom Metadata, Preview of the document file, History of system events. If you need more views of data that are residing in other services, you can add more such aspects. The following example shows TODO.
{
"extensions": []
}
Plug-in Triggers
Form controls supporting the user in entering specific data like String, Numbers, Dates, Booleans, or more specific ones like e-mail addresses, users or references to other objects. If you need more such specific controls you can extend the form controls as shown in the following example:
{
"triggers": []
}
Plug-in Translations
In case you need to extend translations with new keys, please specify translations for each language in your system.
{
"translations": {
"en": {
"yuv.custom.action.home_yuuvis.label": "Yuuvis Home",
"yuv.custom.action.home_yuuvis.description": "Yuuvis Description",
"yuv.custom.action.home_yuuvis.simple": "Yuuvis Home simple",
"yuv.custom.action.home_yuuvis.component": "Yuuvis Home component",
"yuv.custom.action.home_yuuvis.component.full": "Yuuvis Home component full",
"yuv.custom.action.home_yuuvis.link": "Yuuvis Home link",
"yuv.custom.action.home_yuuvis.list": "Yuuvis Home list",
"yuv.custom.trigger.paste.clipboard": "Paste clipboard",
"yuv.custom.trigger.paste.selection": "Paste selection",
"yuv.custom.trigger.paste.suggestion": "Paste suggestion"
},
"de": {
"yuv.custom.action.home_yuuvis.label": "Yuuvis Home DE",
"yuv.custom.action.home_yuuvis.description": "Yuuvis Description DE",
"yuv.custom.action.home_yuuvis.simple": "Yuuvis Home simple DE",
"yuv.custom.action.home_yuuvis.component": "Yuuvis Home component DE",
"yuv.custom.action.home_yuuvis.component.full": "Yuuvis Home component full DE",
"yuv.custom.action.home_yuuvis.link": "Yuuvis Home link DE",
"yuv.custom.action.home_yuuvis.list": "Yuuvis Home list DE",
"yuv.custom.trigger.paste.clipboard": "Paste clipboard DE",
"yuv.custom.trigger.paste.selection": "Paste selection DE",
"yuv.custom.trigger.paste.suggestion": "Paste suggestion"
}
}
}
Activating the Extension Feature and Importing Your Plug-in Configuration
To import a configuration file with your extensions (plug-ins), follow these steps:
- Open the client and open the settings.
- Click the On button in the Plug-in Configuration. This feature is offered to all users with the YUUVIS_SYSTEM_INTEGRATOR role.
- Click on the Import button.
The file is uploaded to the Configuration Service so that all clients can use these extensions as well.
Removing the Configuration
Import an empty JSON file to remove the configuration.
Use Case Example
The following code block configures an action where a start form for a workflow process is offered.
{
"id": "yuv.custom.action.taskflow.id",
"label": "yuv.custom.action.taskflow.label",
"description": "yuv.custom.action.taskflow.description",
"priority": 1,
"icon": "<svg height=\"24\" viewBox=\"0 0 24 24\" width=\"24\" xmlns=\"http://www.w3.org/2000/svg\"> <path d=\"M0 0h24v24H0V0z\" fill=\"none\"></path> <path d=\"M4 10h12v2H4zM4 6h12v2H4zM4 14h8v2H4zM14 14v6l5-3z\"></path> </svg>",
"group": "further",
"range": "MULTI_SELECT",
"isExecutable": "(item) => item.id",
"buttons": {
"finish": "yuv.custom.action.workflow.start"
},
"plugin": {
"component": "yuv-object-form",
"inputs": {
"__initOptions": "() => this.http.get(`/resources/config/taskflow-startform`, 'api-web').then((res) => {component.cmp.options = {formModel: res.data.tenant, disabled: false}})",
"__init": "() =>parent.finished.subscribe((event) => {var selection = parent.selection;var cmp = component.cmp;var vars = [{ name: 'title', type: 'string', value: cmp.formData.title || '' },{ name: 'taskStatus', type: 'string', value: 'Open' },{ name: 'comment', type: 'string', value: cmp.formData.comment },{name: 'nextAssignee',type: 'string',value: cmp.formData.nextAssignee}];if (cmp.formData.expiryDatetime) {vars.push({name: 'expiryDatetime',type: 'date',value: cmp.formData.expiryDatetime,})}this.http.post('/bpm/processes',{businessKey: selection[0].id,name: selection[0].title || selection[0].id,processDefinitionKey: 'dms-lite-taskflow',attachments: selection.map((s) => s.id),subject: selection[0].title,variables: vars,},'api-web').then(() =>this.util.notifier.success(this.util.translate('yuv.custom.action.taskflow.success')))})"
},
"outputs": {
"statusChanged": "(status) => { parent.disabled = status.invalid; }"
}
}
},
The configured action retrieves the form taskflow-startform from the configuration resources. The framework component yuv-object-form offers the form via the object action menu:
The form displays the localized fields corresponding to the Flowable process variables: title (The task), expiryDatetime (Due until), comment (Comment for the next assignee) and nextAssignee (Next assignee).
The variable taskStatus that is internally used for the process management is not displayed.
The variable expiryDatetime can be saved only by calling the process dms-lite-taskflow if a value is set. Thus, it is possible to prohibit setting a null value for the datetime variable which is not allowed in Flowable.
Summary
We have shown how you can extend the reference client or your custom client that is based on our core and framework libraries with custom elements.