Actions are one of the core components of Touch Portal. As a plug-in developer you can define actions for your plug-in that the user can add to their flow of actions in their buttons and events. An action is part of a Category and can be defined as a JSON object.
On the right you can see examples of both static and dynamic actions. Static Actions are actions that can be run without communication. Touch Portal allows communication between the plugin and Touch Portal but for some actions this is not required. For these situations you can use the static actions. This allows for developers to create plugins easier without to much hassle. With dynamic actions you are required to set up and run an application or service that communicates with Touch Portal. With static actions you can use commandline execution that will run directly from Touch Portal.
The attributes of the Action JSON object;
| Key | Type | Req. | API | 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 | No | 7.0 | Language specific version of the name. Add _nl (name_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. |
| 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 | No | 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 | 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 plugin folder. |
| data | Array | No | 1.0 | This is a collection of action data (see definition further down this page) which can be specified by the user. These data id's can be used to fill up the execution_cmd text or the format (see example on the right side). |
| lines | Object | Yes | 7.0 | This is the object for specifying the action and/or onhold lines. Check the Lines Object below. |
| subCategoryId | Text | No | 7.0 | This attribute allows you to connect this action to a specified subcategory id. This action will then be shown in Touch Portals Action selection list attached to that subcategory instead of the main parent category. |
| 1.0 | ||||
| 7.0 | DEPRECATED From API 7 Touch Portal does not support popup windows anymore and all actions need to be defined with the lines attribute. This prefix was used when no format was being present. |
|||
| 7.0 | DEPRECATED From API 7 Touch Portal does not support popup windows anymore and therefor the description will not be shown in the popup message anymore as it will not be present anymore. The description for inline actions from version 2.0 has been deprecated and you should use the lines attribute. |
|||
| 7.0 | DEPRECATED From API 7 Touch Portal does not support popup windows anymore and all actions need to be defined with the lines attribute. |
|||
| format | Text | Yes | 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. |
| 7.0 | DEPRECATED From API 7 the format attribute has been replaced by the lines attribute. |
|||
|
|
||||
| 7.0 | DEPRECATED From API 7 you are not required to specify whether an action also has an on hold component. This is derived from whether or not the action has on hold lines. If there are lines for the on hold functionality this action is automatically added to the on hold actions. |
The lines object consist of the parts; the action lines and the onhold lines. You can specify either or both. Those arrays then consist of lines information per supported language.
| Key | Type | Req. | Api | Description |
|---|---|---|---|---|
| action | Array | No | 7.0 | This is the array for lingual action line information. Each entry in this array should represent line information for a specific language that Touch Portal supports. Use "default" for the English language. The default should always be present in this array. If it is not, the lines will not be rendered in Touch Portal. |
| onhold | Array | No | 7.0 | This is the array for lingual onhold line information. Each entry in this array should represent line information for a specific language that Touch Portal supports. Use "default" for the English language. The default should always be present in this array. If it is not, the lines will not be rendered in Touch Portal. |
Each of the Lines Collection Object consists of an array of lingual lines objects. Each object representing the rendering of the action in a different language.
| Key | Type | Req. | Api | Description |
|---|---|---|---|---|
| language | Text | Yes | 7.0 | This is the country code of the language this line information contains. Use "default" for the English language. The default should always be present.If it is not, the lines will not be rendered in Touch Portal even if you have language specific lines. |
| data | Array | Yes | 7.0 | This is the array of line objects representing the lines of the action. This array should have at least 1 entry. We suggest to not use more than 3 lines to keep action lists clean and clear. Use a maximum of 8 lines in your actions as that will reduce the usability for the end user as the actions might get to big on smaller screens to properly view and scroll. |
| suggestions | Object | Optional | 7.0 | This is a suggestions object where you can specify certain rendering behaviours of the action lines. These are suggestions and my be overruled in certain situations in Touch Portal. One example is rendering lines for different action rendering themes in Touch Portal. |
This object represents a line in an rendered action.
| Key | Type | Req. | Api | Description |
|---|---|---|---|---|
| lineFormat | Text | Yes | 7.0 | This will be the format of the rendered line in the action. Use
the id's of the data objects to place them within the text.
Example given: "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. |
The attributes of the aforementioned suggestions object;
| Key | Type | Req. | API | Description |
|---|---|---|---|---|
| firstLineItemLabelWidth | Number | No | 7.0 | This option will set the width of the first part on a line if it is text. This can be used to make your action more clear for our users. This can be usefull when you list one item to set per line. |
| lineIndentation | Number | No | 7.0 | This option will add padding on the left for each line of a multiline format. If this is used together with firstLineItemLabelWidth the padding will be part of the that width and will not be added onto it. |
This shows a JSON of an action that does not require communication with a plugin application (static). The action is set up to use powershell to create a beep sound when it is executed.
This shows a JSON of an action that does require communication with a plugin application (dynamic). When executed, it will send the information the user has entered in the text field with id (tp_pl_002_text) to the plug-in. Touch Portal will parse the id from the format line and will present the user with the given control to allow for user input.
This shows a JSON of an action that has multiple lines in the action and also has multiple language support.
As a plug-in developer you can augment your actions with additional data that the user has to fill in. It uses the same structures as the native actions from Touch Portal itself.
You can use this for both static actions as dynamic actions. The user will have to specify values for the given data field within Touch Portal. This can be inline like in version 2.1 or it can be done through a popup window. This also depends on the amount of data fields. The following objects can be used in the action array of a category:
Each data object has its own combination of mandatory fields, use the example provided to create data fields. Below are the types and the explanation.
| Key | Type | Req. | Api | 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:
|
|||||||||||||
DEPRECATED From API 7 Touch Portal does not support popup windows anymore and all actions need to be defined with the format attribute. This label was used when no format was being present. |
||||||||||||||
| 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 | Array | No | 1.0 | This is a collection of strings that the user can choose from. | ||||||||||
| extensions | Array | No | 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 | No | 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 | No | 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 | No | 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. | ||||||||||
This shows a JSON of an action data of the type text which will present the user with a text field where the user can enter a value. The textfield will be prefilled with the default value "any text".
This shows a JSON of an action data of the type number which will present the user with a number field. The number field only accepts values between (and including) 100 and 350. The field will be prefilled with the default value 200 when the action is created.
This shows a JSON of an action data of the type choice which will present the user with a drop down selection box. The user will be able to select one of the predefined options. In this case the predefined default option 200 is selected when the action is created.
This shows a JSON of an action data of the type switch which will present the user with an option to either set is as on or as off.