Intro Plugin Structure Categories Static Actions Action Data Dynamic Actions States Events Connectors Settings Notifications Reference Troubleshooting Example SDKs

Dynamic Action structure

The following section will explain the structure of a dynamic action.

Defining dynamic actions

The dynamic actions use the same syntax as the static actions do. You can find the specifics on that section. The big difference to a static action is that this action will communicate data through a socket. The plugin can accept the incoming data and act on it.

Set up communication with Touch Portal

If you use actions in your plugin that are of the type "communicate", Touch Portal will start to listen for communication. From version 3 of the plug-in API, all communication is done in UTF-8 encoding.

Step 1: Open socket

First step is to make a connection to the local host using the ip 127.0.0.1 on the port 12136.

Step 2: Pairing the plugin

Once the connection is made, we need to let Touch Portal know who we are. The first thing you need to send is the pairing message.

{
  "type":"pair",
  "id":"(plugin_id)"
}

This is data in a JSON format. Touch Portal communicates with JSON formatted strings. So ensure that each call you make to Touch Portal is in the JSON format. Sending a piece of data to Touch Portal should always end with a newline character. This will indicate Touch Portal that it is the whole message.

This pairing message will let Touch Portal know what plugin is communicating on this socket. Touch Portal will send all communicate actions through this channel with the given id's.

Touch Portal will return an info message when the pairing is successful

{
  "type":"info",
  "sdkVersion":"(SDK version code)",
  "tpVersionString":"(Version of Touch Portal in string format)",
  "tpVersionCode":"(Version of Touch Portal in code format)",
  "pluginVersion":"(Your plug-in version)"
}

Receiving data from Touch Portal

Touch Portal will send messages on several occasions. Your plug-in should handle them appropriatly.

1. When actions are triggered by the user (Api 1.0+)

Touch Portal will send messages when an action is being triggered (when the button containing one of your plug-in actions is pressed or when an event is triggered that contains your action.) Your plug-in software needs to handle these messages and act on it of course.

{
  "type":"action",
  "pluginId":"id of the plugin",
  "actionId":"id of the action",
  "data": [
    {
      "id":"data object id",
      "value":"user specified data object value"
    },
    {
      "id":"data object id",
      "value":"user specified data object value"
    }
  ]
}

1b. When the action is used in a hold functionality (Api 3.0+)

Touch Portal will send messages to your plugin when the action is used in a hold button event. When the user presses the Touch Portal button down, Touch Portal will send the "down" event. When the user releases the button, Touch Portal will send the "up" event. Only actions that have hold settings can be used in Touch Portal in the Hold tab.

{
  "type":"the state of the button for this action ('up' or 'down')",
  "pluginId":"id of the plugin",
  "actionId":"id of the action",
  "data": [
    {
      "id":"data object id",
      "value":"user specified data object value"
    },
    {
      "id":"data object id",
      "value":"user specified data object value"
    }
  ]
}

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"
    }
  ]
}

1d. When a short id for a connector is generated. (Api 5+)

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.

{
  "type":"shortConnectorIdNotification",
  "pluginId":"id of the plugin",
  "shortId":"shortid of the connector",
  "connectorId":"the long normal connector id"
}

2. When a user makes a change in one of your lists (Api 1.0+)

Touch Portal will send messages when a list of choices value is changed. Your software needs to handle these messages and act on it if you want to use this functionality.

{
  "type":"listChange",
  "pluginId":"id of the plugin",
  "actionId":"id of the action",
  "listId":"id of the list being used in the inline action",
  "instanceId":"id of the instance",
  "value":"newValue"
}

3. When Touch Portal tries to close your plug-in (Api 2.0+)

Touch Portal will send a message when it is closing the plugin for some reason. Touch Portal will also try to close the process. This will happen approximately after 500 ms. This will only happen if the process is being started through the entry.tp start command attribute.

{
  "type":"closePlugin",
  "pluginId":"id of the plugin"
}

4. When Touch Portal broadcasts a message (Api 3.0+)

Touch Portal will send messages to the plug-in at certain events.

{
  "type":"broadcast",
  "event":"pageChange",
  "pageName":"name of the page switched to"
}

You can use this broadcast to resend states whenever a page is loaded. This will allow the user to get the latest states just as a page is loaded.

Attribute Type Mandatory From version Description
type Text yes 3.0 The "broadcast" corresponts to a message type that is send from Touch Portal to all plug-ins. This is information non specific to your plug-in.
event Text yes 3.0 The type of broadcast event that is triggered. Currently only the "pageChange" is supported.
pageName Text Optional 3.0 The value will be send only when the broadcast is of the type "pageChange".

Sending data to Touch Portal

Your plug-in can also send information to Touch Portal.

1. Updating states

Now that we have a connection, we can send state updates to Touch Portal. More information about states, see the state section on the left menu. You can only change the states from your own plug-in. Changing states of Touch Portal itself may result in undesired behaviour.

Sending a piece of data (a message) to Touch Portal should always end with a newline character. This will indicate Touch Portal that it is the whole message.

{
  "type":"stateUpdate",
  "id":"musicState",
  "value":"Playing Music"
}

In this case, Touch Portal will change the state with id "musicState" to "Playing Music". You can specify states and events (which will be triggered by state) to work with states. Read more on this in the section on the left menu.

Attribute Type Mandatory From version Description
type Text yes 1.0 The "stateUpdate" corresponts to a message type to update a state within Touch Portal.
id Text yes 1.0 The state id to set/update
value Text Yes 1.0 The value of the state. Ensure this is a text and nothing else. Touch Portal will handle this value as a piece of text (string)

2. Updating Lists

You can also update state lists in Touch Portal.

Sending a piece of data (a message) to Touch Portal should always end with a newline character. This will indicate Touch Portal that it is the whole message.

{
  "type":"choiceUpdate",
  "id":"musicState",
  "value":[
    "Value1",
    "Value2",
    "Value3"
  ]
}

In this case, Touch Portal will show a different list for choice data with the given id.

Attribute Type Mandatory From version Description
type Text yes 1.0 The type of message. Currently the only option is "choiceUpdate". This will let Touch Portal know that we are about to change a choice list.
id Text yes 1.0 The state id to set/update
value Collection Yes 1.0 The collection of texts that should be the new list to display for this given choice list id.

3. Updating Specific Lists

You can also update specific lists in Touch Portal. This is different from state lists as these will update the dropdown list associated. Still this is very handy when you want to fill in a list for the user based on changes in your plug-in.

Sending a piece of data (a message) to Touch Portal should always end with a newline character. This will indicate Touch Portal that it is the whole message.

Please note, This functionality only works for inline actions. Actions with a popup window do not support this functionality.

{
  "type":"choiceUpdate",
  "id":"musicState",
  "instanceId":"(ID_OF_ACTION_INSTANCE)",
  "value":[
    "Value1",
    "Value2",
    "Value3"
  ]
}

In this case, Touch Portal will show a different list for choice data with the given id.

Attribute Type Mandatory From version Description
type Text yes 1.0 The type of message. Currently the only option is "choiceUpdate". This will let Touch Portal know that we are about to change a choice list.
id Text yes 1.0 The state id to set/update
value Collection Yes 1.0 The collection of texts that should be the new list to display for this given choice list id.
instanceId Text Optional 1.0 This is the id of the instance that should be updated by this call.

4. Create a state at runtime

You can create states at runtime.

{
  "type":"createState",
  "id":"horseCount",
  "desc":"Number of horses",
  "defaultValue":"0",
  "forceUpdate":false
}
Attribute Type Mandatory From version Description
type Text yes 2.0 The type of message.
id Text yes 2.0 The id of the newly created plug-in state. Please ensure unique names, otherwise you may corrupt other plug-ins.
desc Text Yes 2.0 The displayed name within Touch Portal which represents the state.
defaultValue Text Yes 2.0 The default value the state will have on creation.
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.
forceUpdate Switch Optional 7.0 This will force the update of the state if it is already created or existing and will trigger the state changed event even if the value is the same as the already existing one.

5. Remove a state at runtime

You can remove states at runtime.

{
  "type":"removeState",
  "id":"horseCount"
}
Attribute Type Mandatory From version Description
type Text yes 2.0 The type of message. "removeState" is the type to remove the state.
id Text yes 2.0 The id of the plug-in state to remove.

6. Updating Specific action data (Api 3.0+)

You can change the characteristich of certain action data using this message.

Sending a piece of data (a message) to Touch Portal should always end with a newline character. This will indicate Touch Portal that it is the whole message.

{
  "type":"updateActionData",
  "instanceId":"(ID_OF_ACTION_INSTANCE)",
  "data":{
    "minValue":1,
    "maxValue":10,
    "id":"idname_unique",
    "type":"number"
  }
}

At this moment you can only change the minValue and the maxValue attributes of action data.

Attribute Type Mandatory From version Description
type Text yes 3.0 The type of message. Currently the only option is "updateActionData". This will let Touch Portal know that we are about to change action data.
instanceId Text Optional 3.0 This is the id of the instance that should be updated by this call.
data Object Yes 3.0 The object containing all new data for the action data object
data.minValue Number Yes 3.0 The new minimal value for the action data
data.maxValue Number Yes 3.0 The new maximum value for the action data
data.id Text Yes 3.0 The id of the action data to be altered
data.type Text Yes 3.0 We only support this for the type "number" at this moment.

7. Update a setting (Api 3.0+)

With this option you can update a setting from your plug-in. This will overwrite the user setting.

{
  "type":"settingUpdate",
  "name":"name of setting"
  "value":"value to set"
}
Attribute Type Mandatory From version Description
type Text yes 3.0 The type of message. "settingUpdate" is the type to update a setting.
name Text yes 3.0 The name of the settings, should be case sensitive correct
value Text yes 3.0 The new value the setting should hold