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.

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.

Example for adding a new state to the client

{
"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.

Example for adding a new item to the main menu

{
  "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.

Example for adding a new state to the client

{
	"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.

Example for adding a new action to the object actions menu

{
  "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.

Example for adding a new aspect to the object details

{
"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:

Example for adding a custom functionality to the form field controls

{
"triggers": []
}

Plug-in Translations

In case you need to extend translations with new keys, please specify translations for each language in your system.

Example for adding a custom functionality to the form field controls

{
  "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.

Read on

yuuvis® client as reference implementation

yuuvis® client is a reference implementation, browser-based working environment for the daily work with the yuuvis® Momentum system. The client enables the work with documents and metadata (Document Management System) and provides a basis for further modeled business applications. Keep reading

Custom Client Build with Libraries

Documentation of the client core and framework libraries, as usable for custom client development. Keep reading

Client Scripting API

This article describes the Client Scripting API used to develop custom clients as well as client-side form scripts. For more information on building custom clients, refer to the client API documentation. Keep reading

Table of Contents

Browser not supported