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.

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

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

2. When a user makes a change in one of your lists

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

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

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.

{
  "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.