Connectors are the actions that can be connected to control types in Touch Portal such as sliders. A connector works the same way as most other elements such as the action. A user will be able to connect the connector to a Slider control and from that moment the slider will send data from that connector and the slider value to the plug-in.
In Touch Portal you can augment your connector with additional data that the user has to fill in. It uses the same structures as the native actions from Touch Portal itself. If you want to see examples of this, checkout the action section.
The following is an example of a data object you can add to an connector. All data objects are inlined in the connector. Use the format to properly set up the connector to show the correct intuitive usage.
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.
| Attribute | Type | Mandatory | From version | Description |
|---|---|---|---|---|
| id | Text | yes | 4.0 | This is the id of the connector. It is used to identify the connectors 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 mix it up with a different plug-in. Best practise is to create a unique prefix for all your actions like in our case; tp_yourplugin_connector_001. |
| name | Text | yes | 4.0 | This is the name of the connector. This will be used as the connector name in the connector category list. |
| format | Text | yes | 4.0 | This will be the format of the inline connector. Use the id's of the
data objects to place them within the text. Example given: "format":"Control {$connectordata001$} which has {$connectordata002$} and number {$connectordata003$} is {$connectordata004$}", This is a fictive form but it shows how to use this. The data object with the id 'connectordata001' will be shown at the given location. To have an data object appear on the connector line, use the format {$id$} where id is the id of the data object you want to show the control for. |
| data | Collection | Optional | 4.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 format attribute. |
Touch Portal will send messages to your plugin when the connector is used in a connector event. Currently this is when a user has connected the connector to a slider and uses the slider control to change the value. This will trigger the "connectorChange" type of message. The value is an integer number ranging from 0 to 100.
Touch Portal will send the connector data and value in the following way:
Touch Portal will send a value when the user presses his finger on the associated slider. While the finger is still pressing on the slider control it will send every 100ms the value. If the value is not updated because the finger does not move it will not resend the same value. The 100ms is also an indication and can be slower on different set ups and network quality. The minimum however is 100ms.
The slider will always send at least two messages. When the user presses the slider like a button, the same value will be send twice due to the UP and DOWN event.
Whenever a user creates a connector for the first time a shortId is generated for that connector that represents the long connectorId. This short id is useful for when you create long connector ids and the id will be longer than the max of 200 characters.
You can use this shortId instead of the long connectorId to update the connector value in Touch Portal.
This message can be send by Touch Portal on several occassions and can be sent multiple times per connectorId and shortId combination.
Connectors within Touch Portal can be bi-directional. This means that your plug-in will receive updates when the user uses a slider that has your connector connected but it also means that your plug-in is able to update the connector value within Touch Portal which will update the slider position as well.
You can update connectors as a whole. This means that every control that has the connector will show the change, you cannot single out a specific control. This is because the nature of connectors is that they always represent the current state if used bi-directional.
When sending the value to Touch Portal, please be advised that Touch Portal will throttle the communication by sending an update of the value to the mobile device each 100ms. This 100ms is an indication and can be slower on different set ups and network quality. The minimum however is 100ms.
To update the connector data use the following structure:
| Attribute | Type | Mandatory | From version | Description |
|---|---|---|---|---|
| type | Text | yes | 4.0 | The type of message. "connectorUpdate" is the type to update a connector state. |
| connectorId | Text | yes | 4.0 | The id of the connector. This has the following syntax for connectors: pc_pluginId_connectorId Then for each data object it will include a pipe plus the combination of the id and the value of the data object. Example: |dataId=uservalue This will result in a long id for this particular connector, for example: pc_testpluginid_connectorid1|setting1=testvalue|setting2=anothervalue Touch Portal will not allow id's longer than 200 characters so keep this as small as possible |
| Optional | 5.0 | From version 5.0 you can use the shortId instead of the connectorId for communication. Therefore this is no longer a mandatory field from this version. | ||
| shortId | Text | yes | 5.0 | This is a small by Touch Portal generated representation of the connectorId. Please understand that this is just a mapping from the short id to the full connectorId and has not dynamic function. |
| value | Number | yes | 4.0 | A value from 0-100. All other values will be ignored. |