This is the full reference of all the objects:
| 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 |
| 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 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.
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. | ||||||||
| connectors | Collection | Optional | 4.0 | This is the collection that holds all the connectors. More on this in the connectors section. | ||||||||
| states | Collection | Yes | 1.0 | This is the collection that holds all the states. More on this in the states section. | ||||||||
| 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 practice 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. |
| name_(languagecode) | Text | yes | 7.0 | Language specific version of the name. Add _nl for example for the Dutch translation. Ensure to only use langauges supported in Touch Portal. Currently these are nl, de, es, fr, pt and tr. This is the list as of the end of 2022. Be sure to check the language settings in Touch Portal if you want to add a different language. |
| 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. | |||
| description_(languagecode) | Text | Optional | 7.0 | Language specific version of the description. Add _nl for example for the Dutch translation. Ensure to only use langauges supported in Touch Portal. Currently these are nl, de, es, fr, pt and tr. This is the list as of the end of 2022. Be sure to check the language settings in Touch Portal if you want to add a different language. |
| 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. |
| format_(languagecode) | Text | Optional | 7.0 | This will be the format of the inline action for a specific language.
All the same applies as
the default format. In any case you must add the default as well
to be able to use these language based versions.
(lang_code) should be a 2 digit language code. Examples: format_nl will be used for Dutch users format_de will be used for German users Ensure to only use langauges supported in Touch Portal. Currently these are nl, de, es, fr, pt and tr. This is the list as of the end of 2022. Be sure to check the language settings in Touch Portal if you want to add a different language. |
| hasHoldFunctionality | Switch | Optional | 3.0 | Adding this attribute to the action will allow the action to be used with the Hold functionality. The action will appear in the list when the user wants to add actions to the hold functionality. This switch will only work with dynamic actions. Options are "true" or "false". Default is false. |
| 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:
|
||||||||||
| 2.0 | The type of data:
|
|||||||||||||
| 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". | ||||||||||
| minValue | Number | Optional | 3.0 | This is the lowest number that will be accepted. The user will get a message to correct the data if it is lower and the new value will be rejected. | ||||||||||
| maxValue | Number | Optional | 3.0 | This is the highest number that will be accepted. The user will get a message to correct the data if it is higher and the new value will be rejected. | ||||||||||
| 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 practice 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" (#AARRGGBB) 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. It has to be a squared image. |
|||
| 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. |
| parentGroup | Text | Optional | 6.0 | The name of the parent group of this state. The parent group of this state will be used to group the state in the menus used throughout Touch Portal. Every state belonging to the same parent group name will be in the same selection menu. |
| 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. |
| Attribute | Type | Mandatory | From version | Description |
|---|---|---|---|---|
| name | Text | Yes | 3.0 | This is the name of the settings in the settings overview. This is also the identifier. |
| default | Text | Optional | 3.0 | This will be the default value for your setting. |
| type | Text | Yes | 3.0 | This will specify what type of settings you can use. Currently you can only use "text" or "number". |
| maxLength | Number | Optional | 3.0 | This is the max amount of characters a text settings value can have. |
| isPassword | Switch | Optional | 3.0 | If the setting is of the type "password" you should enable this as it will hide the characters from the input field. It will show dots instead. Please do know that communication between Touch Portal and the plug-in is open text. This option is made so that random people will not be able to peek at the password field. It is not secure. |
| minValue | Number | Optional | 3.0 | The minimum number value allowed for a number type setting. |
| maxValue | Number | Optional | 3.0 | The maximum number value allowed for a number type setting. |
| readOnly | Switch | Optional | 3.0 | For some settings you do not want the user to edit them but you do want to share them. Using this switch will allow you to do so. Updating these setting values should be done with the dynamic functions. |
| Attribute | Type | Mandatory | From version | Description |
|---|---|---|---|---|
| notificationId | Text | Yes | 4.0 | This is the id of this notification. Every notification with a unique id will have its own entry in the notification center. The same id should be used for the same kind of message to the user. For example; if you want to show a notification to update to a specific version, use the same id each time you send this notification. This will just show the one notification to the user. |
| title | Text | Yes | 4.0 | This is the title of the notification. |
| msg | Text | Yes | 4.0 | This is the message that is shown in the notification to the user. |
| options | Collection | Yes | 4.0 | This is the collection of options to go with your notification. When a user clicks on the action it will be send to the plugin. The plug-in then can react on the choice the user made. Usually this will contain only one option such as an "Update" or "More Info" option. At least one option is required. |
| Attribute | Type | Mandatory | From version | Description |
|---|---|---|---|---|
| id | Text | Yes | 4.0 | This is the id of the notification option. This id will be send back to the plug-in if the user selects the option. |
| title | Text | Yes | 4.0 | This is the title of the notification option. |
| Attribute | Type | Mandatory | From version | Description |
|---|---|---|---|---|
| title | Text | Optional | 7.0 | This is the title for the tooltip. If this is not added or is left empty, the title will not be shown in the tooltip. |
| body | Text | Yes | 7.0 | This is the body for the tooltip. This text is mandatory. |
| docUrl | Text | Optional | 7.0 | This is the url to the documentation if this is available. If this is empty, no link to documentation is added in the tooltip. |