Actions

From MSX - Wiki
Revision as of 12:06, 18 May 2021 by Benzac (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

All actions are indicated as strings and are used by content items to perform specific tasks (e.g. play a video, start a slideshow, etc.). Some actions use additional data, provided by the corresponding content item.

Note: The actions described here are the main actions that are perfectly adequate for the most media pages. However, if you want to create more complex and interactive media pages, please have a look at the Internal Actions.

Basic Actions[edit]

Action syntax of basic actions
Syntax Example Since Version Description
video:{URL} video:http://msx.benzac.de/media/video1.mp4 0.1.0

Plays a video. The {URL} part must be replaced with the video URL.

audio:{URL} audio:http://msx.benzac.de/media/audio1.mp3 0.1.0

Plays an audio file. The {URL} part must be replaced with the audio URL. This action works in the same way as video:{URL}, except that the video screen is not displayed. Instead, the background screen is displayed. If the corresponding content item provides a background property, it is used, otherwise the next available background property (at higher level) is used.

image:{URL} image:http://msx.benzac.de/img/bg1.jpg 0.1.0

Shows an image. The {URL} part must be replaced with the image URL.

image:context image:context 0.1.0

Shows an image by using the current context. The image URL must be provided as image property by the corresponding content item.

link:{URL} link:http://msx.benzac.de/info/ 0.1.0

Opens a link. The {URL} part must be replaced with the link URL.

link:window:{URL} link:window:http://msx.benzac.de/info/ 0.1.0

Opens a link in a separate window or in an external browser. The {URL} part must be replaced with the link URL.

playlist:{URL} playlist:http://msx.benzac.de/info/data/guide/videos.json 0.1.0

Loads a playlist without a corresponding content page. The {URL} part must be replaced with the playlist URL. The data structure is the same like the Templated Items from the Content API. Please see Content Root Object for more information.

Note: Please note that it is also possible to indicate request actions instead of URLs (e.g. "playlist:request:interaction:{DATA_ID}@{URL}").

playlist:data playlist:data 0.1.0

Starts a playlist without a corresponding content page. The playlist data must be provided as data property by the corresponding content item. The data structure is the same like the Templated Items from the Content API. Please see Content Root Object for more information.

slideshow:{URL} slideshow:http://msx.benzac.de/info/data/guide/images.json 0.1.0

Loads a slideshow without a corresponding content page. The {URL} part must be replaced with the slideshow URL. The data structure is the same like the Templated Items from the Content API. Please see Content Root Object for more information.

Note: Please note that it is also possible to indicate request actions instead of URLs (e.g. "slideshow:request:interaction:{DATA_ID}@{URL}").

slideshow:data slideshow:data 0.1.0

Starts a slideshow without a corresponding content page. The playlist data must be provided as data property by the corresponding content item. The data structure is the same like the Templated Items from the Content API. Please see Content Root Object for more information.

menu:{URL} menu:http://msx.benzac.de/info/data/guide/actions.json 0.1.0

Loads a menu. The {URL} part must be replaced with the menu URL. Please see Menu Root Object for the data structure.

Note: Please note that it is also possible to indicate request actions instead of URLs (e.g. "menu:request:interaction:{DATA_ID}@{URL}").

menu:data menu:data 0.1.0

Shows a menu. The menu data must be provided as data property by the corresponding content item. Please see Menu Root Object for the data structure.

content:{URL} content:http://msx.benzac.de/info/data/guide/videos.json 0.1.0

Loads a content page. The {URL} part must be replaced with the content URL. Please see Content Root Object for the data structure.

Note: Please note that it is also possible to indicate request actions instead of URLs (e.g. "content:request:interaction:{DATA_ID}@{URL}").

content:data content:data 0.1.0

Shows a content page. The content data must be provided as data property by the corresponding content item. Please see Content Root Object for the data structure.

panel:{URL} panel:http://msx.benzac.de/info/data/guide/panel.json 0.1.0

Loads a content page in a panel. The {URL} part must be replaced with the content URL. Please see Content Root Object for the data structure.

Note: Please note that it is also possible to indicate request actions instead of URLs (e.g. "panel:request:interaction:{DATA_ID}@{URL}").

panel:data panel:data 0.1.0

Shows a content page in a panel. The content data must be provided as data property by the corresponding content item. Please see Content Root Object for the data structure.

success:{TEXT} success:This is a success message. 0.1.0

Shows a success message. The {TEXT} part must be replaced with any text. The text supports Inline Expressions.

info:{TEXT} info:This is an info message. 0.1.0

Shows an info message. The {TEXT} part must be replaced with any text. The text supports Inline Expressions.

warn:{TEXT} warn:This is a warning message. 0.1.0

Shows a warning message. The {TEXT} part must be replaced with any text. The text supports Inline Expressions.

error:{TEXT} error:This is an error message. 0.1.0

Shows an error message. The {TEXT} part must be replaced with any text. The text supports Inline Expressions.

focus:{ID} focus:content_item_id 0.1.0

Sets the focus to a specific item in the current context. The {ID} part must be replaced with an item ID (e.g. the content item ID).

focus:index:{INDEX} focus:index:0 0.1.0

Sets the focus to a specific item in the current context. The {INDEX} part must be replaced with an item index (e.g. index 0 will set the focus to the first item).

start start 0.1.30

Sets up a new start parameter. The start parameter data must be provided as data property by the corresponding content item. Please see Start Object for the data structure.

video:plugin:{URL} video:plugin:http://msx.benzac.de/plugins/template.html 0.1.40

Plays a plugin video. The {URL} part must be replaced with the plugin URL. Please see the YouTube, Vimeo & Co. for plugin examples.

audio:plugin:{URL} audio:plugin:http://msx.benzac.de/plugins/template.html 0.1.40

Plays a plugin audio file. The {URL} part must be replaced with the plugin URL. This action works in the same way as video:plugin:{URL}, except that the video screen is not displayed. Instead, the background screen is displayed. If the corresponding content item provides a background property, it is used, otherwise the next available background property (at higher level) is used. Please see the YouTube, Vimeo & Co. for plugin examples.

HbbTV Actions[edit]

If you use the HbbTV version of Media Station X, you have additional actions available.

Action syntax of HbbTV actions
Syntax Example Since Version Description
video:broadcast:current video:broadcast:current 0.1.30

Plays the current broadcast channel.

system:hbbtv:launch:{URL} system:hbbtv:launch:http://msx.benzac.de/hbbtv.html 0.1.30

Launches a new HbbTV application. The {URL} part must be replaced with an HTML page or an XML AIT URL.

For more information about the HbbTV specification, please visit: https://www.hbbtv.org.

Server Actions[edit]

It is possible to execute actions on server side. For this feature, you need programming skills, because you need to implement a service for your server. Server actions allow you to provide logins, member areas, parental controls, search queries, and more. All server actions are sent as HTTP POST requests. Parallel server actions are not allowed (only one server action can be running on application side).

Note: The Content-Type header for all HTTP POST requests is set to application/x-www-form-urlencoded (instead of application/json) to ensure CORS support for simple services (by avoiding CORS preflight requests). Please ignore the Content-Type header on your server and handle all incoming data from the Media Station X application as JSON objects. Since version 0.1.90, you can set an accurate: prefix before {URL} to use the accurate headers (e.g. execute:accurate:{URL}, execute:code:accurate:{URL}, execute:user:accurate:{URL}, etc.).

Action syntax of server actions
Syntax Example Since Version Description
execute:{URL} execute:http://msx.benzac.de/services/echo.php 0.1.30

Executes an action on server side and returns an action to be executed (e.g. to show a success/error message). The {URL} part must be replaced with your service URL. If the corresponding content item provides a data property, it is submitted as data property to your service.

The returned action must be indicated as action property in the data property of a wrapped response object (i.e. in the response.data.action property). Optionally, an action-related data property (of type object) can also be indicated (i.e. in the response.data.data property).

Note: If you return actions like video:{URL} or audio:{URL}, the corresponding content item properties (i.e. playerLabel, background, and properties) must be indicated in the action-related data property (i.e. response.data.data property) in order to be used.

Please see Responses for more information.

execute:code:{URL} execute:code:http://msx.benzac.de/services/echo.php 0.1.30

Executes an action on server side with an entered code and returns an action to be executed (e.g. to show a success/error message). The {URL} part must be replaced with your service URL. If the corresponding content item provides a data property, it is submitted as data property to your service. The code is submitted as code property.

If the corresponding content item provides a data property, it can be used to customize the code panel with following properties.

  • headline: The headline of the code panel; Type: string; Default value: "Enter Code"
  • extension: The extension of the code panel; Type: string; Default value: null
  • value: The initial value of the code panel; Type: string; Default value: null
  • placeholder: The placeholder of the code panel; Type: string; Default value: "Code"
  • secret: Indicates if the entered code is secret and not displayed; Type: boolean; Default value: false

The returned action must be indicated as action property in the data property of a wrapped response object (i.e. in the response.data.action property). Optionally, an action-related data property (of type object) can also be indicated (i.e. in the response.data.data property).

Note: If you return actions like video:{URL} or audio:{URL}, the corresponding content item properties (i.e. playerLabel, background, and properties) must be indicated in the action-related data property (i.e. response.data.data property) in order to be used.

Please see Responses for more information.

execute:user:{URL} execute:user:http://msx.benzac.de/services/echo.php 0.1.30

Executes an action on server side and returns an action to be executed (e.g. to show a success/error message). This action works in the same way as execute:{URL}, except that user credentials (e.g. cookies, authorization headers, etc.) are enabled for this request. Technically, this action sets the withCredentials flag for the XMLHttpRequest object to true.

The user: prefix before {URL} can also be used inside the data property of a menu item and for following actions.

  • execute:code:user:{URL}
  • playlist:user:{URL}
  • slideshow:user:{URL}
  • menu:user:{URL}
  • content:user:{URL}
  • panel:user:{URL}

If you use HTTP sessions and your server manages them via cookies, you should always add the user: prefix.

Note: For this action, the platform must support third-party cookies (a.k.a. cross-site tracking). Typically, this support can be enabled/disabled in the platform settings. Therefore, users should check whether this support is enabled on their platform before using this action. Additionally, please make sure you set the correct CORS HTTP header on server side (namely Access-Control-Allow-Credentials).

Extended Actions[edit]

These actions are useful when working with server actions (e.g. to perform a reload after login or to update content parts after successfully executing an action).

Action syntax of extended actions
Syntax Example Since Version Description
reload reload 0.1.58

Reloads the application.

reload:menu reload:menu 0.1.58 Reloads the current menu data.

Note: The menu data can only be reloaded if it has not been loaded at startup or set via a data action. Since version 0.1.134, you can reload the menu data that has been loaded at startup by using the reference property.

reload:content reload:content 0.1.58

Reloads the current content data.

Note: The content data can only be reloaded if it has not been loaded at startup or set via a data action. Since version 0.1.134, you can reload the content data that has been loaded at startup by using the reference property.

reload:panel reload:panel 0.1.58

Reloads the current panel content data.

Note: The panel content data can only be reloaded if it has not been set via a data action.

update:menu:{ID} update:menu:menu_item_id 0.1.58

Updates the data of a menu item. The {ID} part must be replaced with the menu item ID. The update data must be provided as data property by the corresponding content item. Following data properties can be updated.

  • icon
  • image
  • label
  • background
  • extensionIcon
  • extensionLabel
  • options

Note: Only if the properties have been set (to a non null value) in the origin data, they can be updated. However, the background and options property can always be updated.

Please see Menu Item Object for the data structure.

update:content:{ID} update:content:content_item_id 0.1.58

Updates the data of a content item. The {ID} part must be replaced with the content item ID. The update data must be provided as data property by the corresponding content item. Following data properties can be updated.

  • color
  • title
  • titleHeader
  • titleFooter
  • label
  • icon
  • headline
  • text
  • tag
  • tagColor
  • badge
  • badgeColor
  • progress
  • progressColor
  • wrapperColor
  • image
  • extensionIcon
  • extensionLabel
  • live
  • selection
  • options

Note: Only if the properties have been set (to a non null value) in the origin data, they can be updated. However, the live, selection, and options property can always be updated.

Please see Content Item Object for the data structure.

update:content:overlay:{ID} update:content:overlay:content_item_id 0.1.110

Updates the data of a content overlay item. The {ID} part must be replaced with the content overlay item ID. The update data must be provided as data property by the corresponding content item. Please see action update:content:{ID} for more information about which data properties can be updated.

update:content:underlay:{ID} update:content:underlay:content_item_id 0.1.112

Updates the data of a content underlay item. The {ID} part must be replaced with the content underlay item ID. The update data must be provided as data property by the corresponding content item. Please see action update:content:{ID} for more information about which data properties can be updated.

update:panel:{ID} update:panel:content_item_id 0.1.58

Updates the data of a panel content item. The {ID} part must be replaced with the panel content item ID. The update data must be provided as data property by the corresponding content item. Please see action update:content:{ID} for more information about which data properties can be updated.

update:panel:overlay:{ID} update:panel:overlay:content_item_id 0.1.110

Updates the data of a panel content overlay item. The {ID} part must be replaced with the panel content overlay item ID. The update data must be provided as data property by the corresponding content item. Please see action update:content:{ID} for more information about which data properties can be updated.

update:panel:underlay:{ID} update:panel:underlay:content_item_id 0.1.112

Updates the data of a panel content underlay item. The {ID} part must be replaced with the panel content underlay item ID. The update data must be provided as data property by the corresponding content item. Please see action update:content:{ID} for more information about which data properties can be updated.

data data 0.1.58

This action can be used to execute multiple actions in a row. The actions must be provided as actions property (of type array) in the data property of the corresponding content item. Each action must be indicated as object and must provide an action property (of type string) and can optionally provide an action-related data property (of type object).

Note: If you use actions like video:{URL} or audio:{URL} with this syntax, the corresponding content item properties (i.e. playerLabel, background, and properties) must be indicated in the action-related data property in order to be used.

[{ACTION}|{ACTION}|...] [reload:content|info:Action executed.] 0.1.58

If an action starts with the character [ and ends with the character ], you can use the character | to execute multiple actions in a row. The {ACTION} part must be replaced with any action. If the corresponding content item provides a data property, it is used for each action. By the way, this syntax can also be used to perform a NOP (no operation) action by indicating an empty list (i.e. []).

Note: If you use actions like video:{URL} or audio:{URL} with this syntax, the corresponding content item properties (i.e. playerLabel, background, and properties) must be indicated in the action-related data property in order to be used.