The following section will explain the structure of a plugin description file.
To define a plugin you need to specify it in JSON format. The following block of code show you the basic setup of a plugin.
This is the base of the JSON to describe a plugin. With this you give Touch Portal the information it requires to use it within the Touch Portal environment. The data is as follows:
| Attribute | Type | Mandatory | From version | Description |
|---|---|---|---|---|
| sdk | Number | yes | 1.0 | This should represent the SDK version of Touch Portal this plugin is
build for. Versioning data: Api 1 is introduced in Touch Portal v2.1 Api 2 is introduced in Touch Portal v2.2 Api 3 is introduced in Touch Portal v2.3 Api 4 is introduced in Touch Portal v3.0 Api 5 is introduced in Touch Portal v3.0.6 Api 6 is introduced in Touch Portal v3.0.11 Api 7 is introduced in Touch Portal v3.2 |
| version | Number | yes | 1.0 | A number representing your own versioning. Currently this variable is not used by Touch Portal but may be used in the future. This should be an integer value. So only whole numbers, no decimals. This version value will be send back after the pairing has been done. |
| name | Text | yes | 1.0 | This is the name of the Plugin. This will show in Touch Portal in the settings section "Plug-ins". (From Touch Portal version 2.2) |
| id | Text | yes | 1.0 | This is the unique ID of the Plugin. Use an id that will only be used by you. So use a prefix for example. |
| configuration | Object | Optional | 1.0 | This object is used to specify some configuration options of the plug-in. The child objects of this object are described below. |
| colorDark (Child Object) |
Text | Optional | 1.0 | When users use your actions and events they will be rendered in their own flows.
This attribute tells Touch Portal which dark color to use in those actions and events.
When this is not specified the default plug-in colors will be used in Touch Portal.
Preferably use the color schemes of the software or product you are
making a plug-in for to increase recognizability. Use heximal values
that represent the color you want it to be in the format "#FF0000".
Note: these color will be ignored in some of the themes within Touch Portal. There is no way to override this behaviour. |
| colorLight (Child Object) |
Text | Optional | 1.0 | When users use your actions and events they will be rendered in their own flows.
This attribute tells Touch Portal which dark color to use in those actions and events.
When this is not specified the default plug-in colors will be used in Touch Portal.
Preferably use the color schemes of the software or product you are
making a plug-in for to increase recognizability. Use heximal values
that represent the color you want it to be in the format "#FF0000".
Note: these color will be ignored in some of the themes within Touch Portal. There is no way to override this behaviour. |
| parentCategory (Child Object) |
Text | Optional | 7.0 | From Api 7 you can add your plug-in in specific categories within
Touch Portal. These main categories are used within the category and
action control which the user uses to add an action to a flow of actions.
Use one of the following category ids: audio - for all audio, music and media related plug-ins.
streaming - for all streaming related plug-ins.
content - for all Content Creation related plug-ins.
homeautomation - for all Home Automation related plug-ins.
social - for all social media related plug-ins.
games - for all game related plug-ins.
misc - This is the default category a plugin falls into even when
this attribute of the configuration has not been specified. All plug-ins
not fitting in one of the categories above should be placed in this
category.
|
| plugin_start_cmd | Text | Optional | 1.0 | Specify the path of execution here. You should be aware that it will
be passed to the OS process exection service. This means you need to be
aware of spaces and use absolute paths to your executable. If you use %TP_PLUGIN_FOLDER% in the text here, it will be replaced with the path to the base plugins folder. So append your plugins folder name to it as well to access your plugin base folder. This execution will be done when the plugin is loaded in the system and only if it is a valid plugin. Use this to start your own service that communicates with the Touch Portal plugin system. |
| plugin_start_cmd_windows | Text | Optional | 4.0 (TP v3.0.5+) | This is the same plugin_start_cmd but will only run on a Windows desktop. If this is specified Touch Portal will not run the default plugin_start_cmd when this plug-in is used on Windows but only this entry. |
| plugin_start_cmd_mac | Text | Optional | 4.0 (TP v3.0.5+) | This is the same plugin_start_cmd but will only run on a MacOS desktop. If this is specified Touch Portal will not run the default plugin_start_cmd when this plug-in is used on MacOS but only this entry. |
| plugin_start_cmd_linux | Text | Optional | 4.0 (TP v3.0.5+) | This is the same plugin_start_cmd but will only run on a Linux desktop. If this is specified Touch Portal will not run the default plugin_start_cmd when this plug-in is used on Linux but only this entry. |
| categories | Collection | Yes | 1.0 | This is the collection that holds all the action categories. Categories are used in the action list in Touch Portal. Each Category must contain at least an item such as an action, an event or an connector. More on this in the category section. |
| settings | Collection | Optional | 3.0 | This is the collection that holds all the settings for this plug-in |
This is the base part of the JSON object defining the plugin. In the next section we will explain the structure of the categories.