The structure of the Touch Portal plugin system revolves around the plugin description file. This is a JSON file 'entry.tp' which describes the plugin. Touch Portal loads this files and with the given data, it will create action categories, actions, events, connectors, settings and states within Touch Portal.
The description file is a file containing a JSON object. This object has the following attributes in its root. On the right is an example of how it could look like.
| Key | Type | Req. | Api | Description |
|---|---|---|---|---|
| sdk | Number | yes | 1.0 | DEPRECATED When targeting API 7 and above of the Touch Portal API this key is deprecated and the api key should be used. |
| api | Number | yes | 7.0 | This should represent the API 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 v4.0 Api 8 is introduced in Touch Portal v4.1 Api 9 is introduced in Touch Portal v4.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 | No | 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 | No | 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 | No | 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 | No | 7.0 | 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 | No | 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 | No | 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 | No | 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 | No | 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 | Array | 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 | Array | No | 3.0 | This is the collection that holds all the settings for this plug-in |
This describes a plugin called 'Tutorial SDK Plugin'. It will execute the plugin_start_cmd value when the plugin gets started in Touch Portal. This example does not provide any categories or settings.