Intro Plugin Structure Categories Static Actions Action Data Dynamic Actions States Events Settings Reference Troubleshooting Example SDKs

Plugin Structure

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"
  },
  "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:

Touch Portal v2.1 introduced Api 1
Touch Portal v2.2 introduced Api 2
Touch Portal v2.3 introduced Api 3
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 can be used for coloring the actions and events for the plugin. These colors will be used in the colored theme. In the blue and grey theme this will be ignored. The attributes colorDark and colorLight should be there when you want to specify the colors. The color value is a string hex value, like #FF0000 for red or #00FF00 for green.
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.
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 on item such as an action or an event. 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 strucutre 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.