Reference

This is the full reference of all the objects:

Plugin Structure

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
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.

Categories

Attribute Type Mandatory From version Description
id Text yes 1.0 This is the id of the category.
name Text yes 1.0 This is the name of the category.
imagepath Text Optional 1.0 This is the absolute path to an icon for the category. You can should place this in your plugin folder and reference it. If you use %TP_PLUGIN_FOLDER% in the text here, it will be replaced with the path to the base plugin folder.

Image specs:
Format32bit PNG
Size24x24
ColorWhite icon with transparent background


Although colored icons are possible, they will be removed in the near future.
actions Collection Yes 1.0 This is the collection that holds all the actions. More on this in the actions section.
events Collection Yes 1.0 This is the collection that holds all the events. More on this in the events section.
states Collection Yes 1.0 This is the collection that holds all the states. More on this in the states section.

Actions

Attribute Type Mandatory From version Description
id Text yes 1.0 This is the id of the action. It is used to identify the action within Touch Portal. This id needs to be unique across plugins. This means that if you give it the id "1" there is a big chance that it will be a duplicate. Touch Portal may reject it or when the other action is called, yours will be as well with wrong data. Best practise is to create a unique prefix for all your actions like in our case; tp_pl_action_001.
name Text yes 1.0 This is the name of the action. This will be used as the action name in the action category list.
prefix Text yes 1.0 This is the text that is displayed before the name of the action in the action list of a button.
type Text Yes 1.0 This is the attribute that specifies whether this is a static action "execute" or a dynamic action "communicate".
executionType Text Optional 1.0 This is the attribute that specifies what kind of execution this action should use. This a Mac only functionality. Options: "AppleScript" or "Bash".
execution_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 plugin folder.
description Text Optional 1.0 This will add text to the popup window. It will be shown on the top of the popup. This can be used to explain parts of the plugin data.
2.0 From version 2.0 of the Api (Touch Portal v2.2) this description will also be used in the inline actions on top to be able to add information about the action where applicable.
data Collection Optional 1.0 This is a collection of data which can be specified by the user. These data id's can be used to fill up the execution_cmd text.
tryInline Switch Optional 1.0 Adding this attribute to the action will make this an inline action. User can edit data from the action list instead of a popup. Options are "true" or "false". Default is false.
format Text Optional 1.0 This will be the format of the inline action. Use the id's of the data objects to place them within the text. Example given:

"format":"When {$actiondata001$} has {$actiondata002$} and number {$actiondata003$} is {$actiondata004$}",

This is a fictive form but it shows how to use this. The data object with the id 'actiondata001' will be shown at the given location. To have an data object appear on the action line, use the format {$id$} where id is the id of the data object you want to show the control for.

Action Data

Attribute Type Mandatory From version Description
id Text yes 1.0 This is the id of the data field. Touch Portal will use this for communicating the values or to place the values in the result.
type Text yes 1.0 The type of data:

Types:
textA data type that accepts a string
numberA data type that accepts a number
switchA data type that accepts a true or false value
choiceA data type that accepts a string where a collection of strings can be chosen from


2.0 The type of data:

Types:
fileA data type that represents a file which the user can pick with a file chooser
folderA data type that represents a folder which the user can pick with a folder chooser
colorA data type that represents a color which the user can pick with a color chooser. This value must be in a the format #RRGGBBAA.


label Text yes 1.0 This is the text used in the popup windows
default Text
Number
Switch
Yes 1.0 This is the default value the data object has. Use the correct types of data for the correct type of data object. Eg: The switch data object expects a true or false here.
valueChoices Collection Yes 1.0 This is a collection of strings that the user can choose from.
extensions Collection Optional 2.0 This is a collection of extensions allowed to open. This only has effect when used with the file type.

eg: "extensions": ["*.jpg","*.png",]
allowDecimals Switch Optional 2.0 This field can only be used with the "number" type and tells the system whether this data field should allow decimals in the number. The default is "true".

States

Attribute Type Mandatory From version Description
id Text yes 1.0 This is the id of the state. It is used to identify the states within Touch Portal. This id needs to be unique across plugins. This means that if you give it the id "1" there is a big chance that it will be a duplicate. Touch Portal may reject it or when the other state is updated, yours will be as well with wrong data. Best practise is to create a unique prefix for all your states like in our case; tp_sid_fruit.
type Text yes 1.0 This is the type of state. Currently we only support the type "choice". A choice state is a state where you specify a limited amount of state values the state can be.
2.0 From this version we also support the type "text". This type can be used for smart conversion as well.

"#FF115599" can be interpreted by the plug-in visuals action as a color. The format needs to be this or it will not be seen as a color and will not be converted.

A base64 representation of an image will also be allowed for specific actions such as the plug-in visuals action. This will read the base64 string representation and convert it to an image and show it on the button. We suggest to keep these as small as possible. Images used like this on a button are not stored and only exist temporary. This allows for a performant updating process. Allow for multiple updates per second depending on the computer used, the device used and the quality of the network.

The base64 string should only hold the base64 data. The meta data should be stripped. The format has to be a PNG.
desc Text yes 1.0 This text describes the state and is used in the IF statement to let the user see what state it is changing. We recommend to make this text work in the flow of the inline nature of the IF statement within Touch Portal. This is also the title that is used in list where you can use this state value for logic execution.
default Text Yes 1.0 This is the value the state will have if it is not set already but is looked up.
valueChoices Collection Optional 1.0 Specify the collection of values that can be used to choose from. These can also be dynamically changed if you use the dynamic actions.

Events

Attribute Type Mandatory From version Description
id Text yes 1.0 This is the id of the event. When the event is triggered, Touch Portal will send this information to the plugin with this id.
name Text yes 1.0 This is the name in the action category list.
format Text yes 1.0 This is the text the action will show in the user generated action list. The $val location will be changed with a dropdown holding the choices that the user can make for the status.
type Text Yes 1.0 Currently the only option here is "communicate" which indicates that the value will be communicated through the sockets.
valueChoices Collection Yes 1.0 These are all the options the user can select in the event.
valueType Text Yes 1.0 Currently the only option here is "choice" which indicates that the type of event will be an dropdown with predefined values.
valueStateId Text Yes 1.0 Reference to a state. When this states changes, this event will be evaluated and possibly triggered if the condition is correct.