Connectors (Api 4.0+)

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.

Defining connector data

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.

Table for Defining a Connector

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.

Communication from Touch Portal

1c. When a connector is used in a slider functionality (connector) (Api 4.0+)

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:

  1. On Finger Down, always send
  2. On Finger Move, send each 100ms if value changed.
  3. On Finger Up, always send

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.

{
  "type":"connectorChange",
  "pluginId":"id of the plugin",
  "connectorId":"id of the action",
  "value":integer number between 0-100,
  "data": [
    {
      "id":"data object id",
      "value":"user specified data object value"
    },
    {
      "id":"data object id",
      "value":"user specified data object value"
    }
  ]
}

Communication to Touch Portal

8. Sending Connector data to Touch Portal (connector) (Api 4.0+)

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:

{
  "type":"connectorUpdate",
  "connectorId":"id of the connector",
  "value":integer number between 0-100,
}
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
value Number yes 4.0 A value from 0-100. All other values will be ignored.