Plugin Structure (entry.tp)

The following section will explain the structure of a plugin description file.

Defining the plugin

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.

{
  "sdk":1,
  "version":1,
  "name":"Tutorial SDK Plugin",
  "id":"tp_tut_001",
  "configuration" : {
    "colorDark" : "#FF0000",
    "colorLight" : "#00FF00"
    "parentCategory" : "misc"
  },
  "plugin_start_cmd":"command line execution",
  "categories": [ ...categories... ],
  "settings": [ ...settings... ],
}

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.

Plugin builders should create their own installers. Touch Portal does not provide a way to install the plugin. The reasoning behind this is so plugin builders are not limited by us. This allows:
  • To install more than just the plugin, for example a nodejs server if required.
  • To use your own desired language to code the plugin
  • To be creative in ways we do not even know or predict yet ;-)
  • To pack it with your own software and auto install it during the setup of your own applications
  • To be able to make it a paid plugin and have your own portal to the plugin
So to distribute the plugin you need to supply an installer that will install all the necessary files in the right location. This means the plugin description file needs to be installed in the correct place but all other software required to run your plugin should also be installed by this installer.