How to create a plugin
Overview
On this page, you can learn how to create a plugin and explore a sample plugin example.
How to create a Plugin
Step 1: Manifest reference
The manifest.json must contains the configuration of your plugin and must be included inside the zip file, like in the following example:
Script Example
{
"name": "MyScriptPlugin",
"version": "1.0.0",
"description": "Displays the MyPlugin",
"author": {
"name": "AuthorName",
"email": "name@name.com",
"website": "https://www.name.com"
},
"type": "script",
"sidebar": "always",
"icon": "icon-apps",
"parameters": {
"scriptName": "my-plugin",
"scriptPath": "app/index.js",
}
}
Html Example
{
"name": "MyHtmlPlugin",
"version": "1.0.0",
"description": "Displays the myPlugin",
"author": {
"name": "AuthorName",
"email": "name@name.com",
"website": "https://www.name.com"
},
"type": "html",
"sidebar": "adminOnly",
"icon": "icon-apps",
"parameters": {
"views": {
"admin": "https://www.name.com"
}
}
Name
Specifies a name for the plugin. Required.
Version
Specifies a version number for the plugin. Required.
Description
Specifies the plugin’s functionality. Required.
Author
Specifies the author of the plugin. It contains a JSON object with the following properties:
name: an individual or a company.
email: the address to which users can send support requests.
website: url pointing to a page about the author or the plugin.
Type
Specifies the type of the plugin. Required.
html: displays the url or the custom html page specified.
script: launch the Node.js application provided inside the zip.
Sidebar
Specifies the plugin’s visibility [default: always]
always: visible on both admin’s and agent’s sidebar
adminOnly: visible on the admin’s sidebar only
agentOnly: visible on the agent’s sidebar only
never: hidden on both admin’s and agent’s sidebar
Icon
Specifies the icon that will be displayed on the agent’s sidebar. [default: icon-apps]
Here it’s possible to see all the Motion default icons that can be inserted:
https://fuse-3d648.firebaseapp.com/ui/icons
Pdf Icon List:
Parameters
Contains all the information needed for the correct functioning of the plugin. Required.
scriptName: the name used for the new process when starting the Node.js application. Required for script type plugin only.
scriptPath: the path to where the Node.js application launcher file is located. Required for script type plugin only.
views: a JSON object with the following properties (required for html type plugin only):
admin: an url or the path to a custom html file that will be displayed on the admin side
agent: an url or the path to a custom html file that will be displayed on the agent side
Motion Variables
You can use User Variables in the agent view property (i.e. https://www.name.com?name={{user.name} }))
Step 2: Create the Plugin Application and the .zip file
As an example we consider a Script Plugin.
The application must be developed in node.js like in the following example:
var express = require('express');
var app = express();
app.listen(9006, function () {
console.log('Sample Node Application Plugin Service listening on port ' + 9006);
});
Remember that the pakage.json file must be added in the zip file, according to the node.js specification. For more information click here.
and this is the corresponding manifest.json file:
{
"name": "Sample Script",
"version": "1.0.0",
"description": "Sample plugin developed in Node.js",
"author": {
"name": "Xenialab",
"email": "xenialab@xcally.com",
"website": "https://www.xcally.com/en/"
},
"type": "script",
"sidebar": "always",
"parameters": {
"scriptName": "sample",
"scriptPath": "app/index.js",
"views": {
"admin": "admin/index.html",
"agent": "https://www.xcally.com/en/"
}
}
The script can use the XCALLY Motion style (angular material): in this case it must be defined in the index.html file.
Plugin Sample
In this paragraph we analyse a plugin sample, in which you can view different functionalities that you can do with plugins (how to call Motion, how to connect to socketIO, how to call internal API…).
You can download source code from this link: https://bitbucket.org/xenialab/angular-plugin
in plugin folder, you can find plugin files (manifest, client, server...) to upload on Motion
project contains the frontend Angular project
build.bat: batch file that build the Angular project and create the zip file to be uploaded to XCALLY
To build the plugin you need to follow these instructions:
cd project
npm ci
cd ..
build.batnpm ci installs npm packages
build.bat creates zip for XCALLY
Upload plugin zip in App Zone/Plugins section and then click on Install plugin
At the end of installation, you can open the plugin from Plugins section.
Front-end is developed in Angular 16.
Then the example phrase on the top is only an example of API plugin call. In fact plugin exposes API and in backend server folder, the 'api/test' allows to read JSON and returns in this case a quote
This shows that from the frontend of the plugin, you can call the plugin's API and display the response on the platform.
Instead on api.service.ts you can view that to call plugin internal API, you have to use /api/plugins/webhook, by indicating then port (with the plugin listening) and endpoint url
On Agents tab, it’s visible the list of agents to show an example in the plugin source of how to call Motion API
Consider that no login or authentication is required, because the plugin runs on an iframe served by the same server, so browser sends cookies with authentication saved and it is possible to make API calls directly with the same user used in XCALLY.
SocketIO tab to show that from plugin it’s possible to connect to Motion SocketIO (stable connection between browser and server that remains in communication at all times, e.g. for chat messages, realtime data).
On tail tab, it’s possible to view a server log file. It’s necessary to put socketIO within plugin.
On server part is initialised socketIO, then files are monitored with TailFile and when new data arrive, the plugin sends emit message with data.
Frontend connects to this socketIO and when new data arrive, it shows them on the tab tail
Consider that all plugins you install, server-side, listen on localhost (thus not accessible from the outside).
On system environment level, configuration is required to turn traffic in the correct way.