Difference between revisions of "Actions"
(48 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
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. | 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 == | ||
{| class="wikitable sortable" | {| class="wikitable sortable" | ||
+ | |+ Action syntax of basic actions | ||
|- | |- | ||
! Syntax !! Example !! Since Version !! class="unsortable" | Description | ! Syntax !! Example !! Since Version !! class="unsortable" | Description | ||
Line 9: | Line 12: | ||
|| <code>video:http://msx.benzac.de/media/video1.mp4</code> | || <code>video:http://msx.benzac.de/media/video1.mp4</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Plays a video. The <code>{URL}</code> part must be replaced with the video URL. | + | || |
+ | Plays a video. The <code>{URL}</code> part must be replaced with the video URL. | ||
|- | |- | ||
| <code>audio:{URL}</code> | | <code>audio:{URL}</code> | ||
|| <code>audio:http://msx.benzac.de/media/audio1.mp3</code> | || <code>audio:http://msx.benzac.de/media/audio1.mp3</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Plays an audio | + | || |
+ | Plays an audio. The <code>{URL}</code> part must be replaced with the audio URL. This action works in the same way as <code>video:{URL}</code>, except that the video screen is not displayed. Instead, the background screen is displayed. If the corresponding content item provides a <code>background</code> property, it is used, otherwise the next available <code>background</code> property (at higher level) is used. | ||
|- | |- | ||
| <code>image:{URL}</code> | | <code>image:{URL}</code> | ||
|| <code>image:http://msx.benzac.de/img/bg1.jpg</code> | || <code>image:http://msx.benzac.de/img/bg1.jpg</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Shows an image. The <code>{URL}</code> part must be replaced with the image URL. | + | || |
+ | Shows an image. The <code>{URL}</code> part must be replaced with the image URL. | ||
|- | |- | ||
| <code>image:context</code> | | <code>image:context</code> | ||
|| <code>image:context</code> | || <code>image:context</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Shows an image by using the current context. The image URL must be provided as <code>image</code> property by the corresponding content item. | + | || |
+ | Shows an image by using the current context. The image URL must be provided as <code>image</code> property by the corresponding content item. | ||
|- | |- | ||
| <code>link:{URL}</code> | | <code>link:{URL}</code> | ||
|| <code>link:http://msx.benzac.de/info/</code> | || <code>link:http://msx.benzac.de/info/</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Opens a link. The <code>{URL}</code> part must be replaced with the link URL. | + | || |
+ | Opens a link. The <code>{URL}</code> part must be replaced with the link URL. | ||
|- | |- | ||
| <code>link:window:{URL}</code> | | <code>link:window:{URL}</code> | ||
|| <code>link:window:http://msx.benzac.de/info/</code> | || <code>link:window:http://msx.benzac.de/info/</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|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. | + | || |
+ | Opens a link in a separate window or in an external browser. The <code>{URL}</code> part must be replaced with the link URL. | ||
|- | |- | ||
| <code>playlist:{URL}</code> | | <code>playlist:{URL}</code> | ||
|| <code>playlist:http://msx.benzac.de/info/data/guide/videos.json</code> | || <code>playlist:http://msx.benzac.de/info/data/guide/videos.json</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Loads a playlist without a corresponding content page. The <code>{URL}</code> part must be replaced with the playlist URL. | + | || |
− | The data structure is the same like the '''Templated Items''' from the '''Content API'''. Please see | + | Loads a playlist without a corresponding content page. The <code>{URL}</code> 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. <code>"playlist:request:interaction:{DATA_ID}@{URL}"</code>).''' | ||
|- | |- | ||
| <code>playlist:data</code> | | <code>playlist:data</code> | ||
|| <code>playlist:data</code> | || <code>playlist:data</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Starts a playlist without a corresponding content page. The playlist data must be provided as <code>data</code> property by the corresponding content item. | + | || |
− | The data structure is the same like the '''Templated Items''' from the '''Content API'''. Please see | + | Starts a playlist without a corresponding content page. The playlist data must be provided as <code>data</code> 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. | ||
+ | |||
+ | '''Note: Please note that it is also possible to indicate the data inline as base64-encoded JSON (e.g. <code>"playlist:json:{BASE64_ENCODED_JSON}"</code>).''' | ||
|- | |- | ||
| <code>slideshow:{URL}</code> | | <code>slideshow:{URL}</code> | ||
|| <code>slideshow:http://msx.benzac.de/info/data/guide/images.json</code> | || <code>slideshow:http://msx.benzac.de/info/data/guide/images.json</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Loads a slideshow without a corresponding content page. The <code>{URL}</code> part must be replaced with the slideshow URL. | + | || |
− | The data structure is the same like the '''Templated Items''' from the '''Content API'''. Please see | + | Loads a slideshow without a corresponding content page. The <code>{URL}</code> 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. <code>"slideshow:request:interaction:{DATA_ID}@{URL}"</code>).''' | ||
|- | |- | ||
| <code>slideshow:data</code> | | <code>slideshow:data</code> | ||
|| <code>slideshow:data</code> | || <code>slideshow:data</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Starts a slideshow without a corresponding content page. The playlist data must be provided as <code>data</code> property by the corresponding content item. | + | || |
− | The data structure is the same like the '''Templated Items''' from the '''Content API'''. Please see | + | Starts a slideshow without a corresponding content page. The playlist data must be provided as <code>data</code> 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. | ||
+ | |||
+ | '''Note: Please note that it is also possible to indicate the data inline as base64-encoded JSON (e.g. <code>"slideshow:json:{BASE64_ENCODED_JSON}"</code>).''' | ||
|- | |- | ||
| <code>menu:{URL}</code> | | <code>menu:{URL}</code> | ||
|| <code>menu:http://msx.benzac.de/info/data/guide/actions.json</code> | || <code>menu:http://msx.benzac.de/info/data/guide/actions.json</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Loads a menu. The <code>{URL}</code> part must be replaced with the menu URL. | + | || |
− | Please see | + | Loads a menu. The <code>{URL}</code> 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. <code>"menu:request:interaction:{DATA_ID}@{URL}"</code>).''' | ||
|- | |- | ||
| <code>menu:data</code> | | <code>menu:data</code> | ||
|| <code>menu:data</code> | || <code>menu:data</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Shows a menu. The menu data must be provided as <code>data</code> property by the corresponding content item. | + | || |
− | Please see | + | Shows a menu. The menu data must be provided as <code>data</code> property by the corresponding content item. |
+ | Please see [[Menu Root Object]] for the data structure. | ||
+ | |||
+ | '''Note: Please note that it is also possible to indicate the data inline as base64-encoded JSON (e.g. <code>"menu:json:{BASE64_ENCODED_JSON}"</code>).''' | ||
|- | |- | ||
| <code>content:{URL}</code> | | <code>content:{URL}</code> | ||
|| <code>content:http://msx.benzac.de/info/data/guide/videos.json</code> | || <code>content:http://msx.benzac.de/info/data/guide/videos.json</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Loads a content page. The <code>{URL}</code> part must be replaced with the content URL. | + | || |
− | Please see | + | Loads a content page. The <code>{URL}</code> 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. <code>"content:request:interaction:{DATA_ID}@{URL}"</code>).''' | ||
|- | |- | ||
| <code>content:data</code> | | <code>content:data</code> | ||
|| <code>content:data</code> | || <code>content:data</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Shows a content page. The content data must be provided as <code>data</code> property by the corresponding content item. | + | || |
− | Please see | + | Shows a content page. The content data must be provided as <code>data</code> property by the corresponding content item. |
+ | Please see [[Content Root Object]] for the data structure. | ||
+ | |||
+ | '''Note: Please note that it is also possible to indicate the data inline as base64-encoded JSON (e.g. <code>"content:json:{BASE64_ENCODED_JSON}"</code>).''' | ||
|- | |- | ||
| <code>panel:{URL}</code> | | <code>panel:{URL}</code> | ||
|| <code>panel:http://msx.benzac.de/info/data/guide/panel.json</code> | || <code>panel:http://msx.benzac.de/info/data/guide/panel.json</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Loads a content page in a panel. The <code>{URL}</code> part must be replaced with the content URL. | + | || |
− | Please see | + | Loads a content page in a panel. The <code>{URL}</code> 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. <code>"panel:request:interaction:{DATA_ID}@{URL}"</code>).''' | ||
|- | |- | ||
| <code>panel:data</code> | | <code>panel:data</code> | ||
|| <code>panel:data</code> | || <code>panel:data</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Shows a content page in a panel. The content data must be provided as <code>data</code> property by the corresponding content item. | + | || |
− | Please see | + | Shows a content page in a panel. The content data must be provided as <code>data</code> property by the corresponding content item. |
+ | Please see [[Content Root Object]] for the data structure. | ||
+ | |||
+ | '''Note: Please note that it is also possible to indicate the data inline as base64-encoded JSON (e.g. <code>"panel:json:{BASE64_ENCODED_JSON}"</code>).''' | ||
|- | |- | ||
| <code>success:{TEXT}</code> | | <code>success:{TEXT}</code> | ||
|| <code>success:This is a success message.</code> | || <code>success:This is a success message.</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Shows a success message. The <code>{TEXT}</code> part must be replaced with any text. | + | || |
− | The text supports | + | Shows a success message. The <code>{TEXT}</code> part must be replaced with any text. |
+ | The text supports [[Inline Expressions]]. | ||
|- | |- | ||
| <code>info:{TEXT}</code> | | <code>info:{TEXT}</code> | ||
|| <code>info:This is an info message.</code> | || <code>info:This is an info message.</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Shows an info message. The <code>{TEXT}</code> part must be replaced with any text. | + | || |
− | The text supports | + | Shows an info message. The <code>{TEXT}</code> part must be replaced with any text. |
+ | The text supports [[Inline Expressions]]. | ||
|- | |- | ||
| <code>warn:{TEXT}</code> | | <code>warn:{TEXT}</code> | ||
|| <code>warn:This is a warning message.</code> | || <code>warn:This is a warning message.</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Shows a warning message. The <code>{TEXT}</code> part must be replaced with any text. | + | || |
− | The text supports | + | Shows a warning message. The <code>{TEXT}</code> part must be replaced with any text. |
+ | The text supports [[Inline Expressions]]. | ||
|- | |- | ||
| <code>error:{TEXT}</code> | | <code>error:{TEXT}</code> | ||
|| <code>error:This is an error message.</code> | || <code>error:This is an error message.</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Shows an error message. The <code>{TEXT}</code> part must be replaced with any text. | + | || |
− | The text supports | + | Shows an error message. The <code>{TEXT}</code> part must be replaced with any text. |
+ | The text supports [[Inline Expressions]]. | ||
|- | |- | ||
| <code>focus:{ID}</code> | | <code>focus:{ID}</code> | ||
|| <code>focus:content_item_id</code> | || <code>focus:content_item_id</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Sets the focus to a specific item in the current context. The <code>{ID}</code> part must be replaced with an item ID (e.g. the content item ID). | + | || |
+ | Sets the focus to a specific item in the current context. The <code>{ID}</code> part must be replaced with an item ID (e.g. the content item ID). | ||
|- | |- | ||
| <code>focus:index:{INDEX}</code> | | <code>focus:index:{INDEX}</code> | ||
|| <code>focus:index:0</code> | || <code>focus:index:0</code> | ||
| data-sort-value=0|0.1.0 | | data-sort-value=0|0.1.0 | ||
− | || Sets the focus to a specific item in the current context. The <code>{INDEX}</code> part must be replaced with an item index (e.g. index <code>0</code> will set the focus to the first item). | + | || |
+ | Sets the focus to a specific item in the current context. The <code>{INDEX}</code> part must be replaced with an item index (e.g. index <code>0</code> will set the focus to the first item). | ||
|- | |- | ||
| <code>start</code> | | <code>start</code> | ||
|| <code>start</code> | || <code>start</code> | ||
| data-sort-value=30|'''0.1.30''' | | data-sort-value=30|'''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 | + | Sets up a new start parameter. The start parameter data must be provided as <code>data</code> property by the corresponding content item. |
+ | Please see [[Start Object]] for the data structure. | ||
|- | |- | ||
| <code>video:plugin:{URL}</code> | | <code>video:plugin:{URL}</code> | ||
|| <code>video:plugin:http://msx.benzac.de/plugins/template.html</code> | || <code>video:plugin:http://msx.benzac.de/plugins/template.html</code> | ||
| data-sort-value=40|'''0.1.40''' | | data-sort-value=40|'''0.1.40''' | ||
− | || Plays a plugin video. The <code>{URL}</code> part must be replaced with the plugin URL. | + | || |
− | Please see the | + | Plays a plugin video. The <code>{URL}</code> part must be replaced with the plugin URL. |
+ | Please see the [[YouTube, Vimeo & Co.]] for plugin examples. | ||
|- | |- | ||
| <code>audio:plugin:{URL}</code> | | <code>audio:plugin:{URL}</code> | ||
|| <code>audio:plugin:http://msx.benzac.de/plugins/template.html</code> | || <code>audio:plugin:http://msx.benzac.de/plugins/template.html</code> | ||
| data-sort-value=40|'''0.1.40''' | | data-sort-value=40|'''0.1.40''' | ||
− | || Plays a plugin audio | + | || |
− | Please see the | + | Plays a plugin audio. The <code>{URL}</code> part must be replaced with the plugin URL. This action works in the same way as <code>video:plugin:{URL}</code>, except that the video screen is not displayed. Instead, the background screen is displayed. If the corresponding content item provides a <code>background</code> property, it is used, otherwise the next available <code>background</code> property (at higher level) is used. |
+ | Please see the [[YouTube, Vimeo & Co.]] for plugin examples. | ||
|} | |} | ||
Line 153: | Line 201: | ||
{| class="wikitable sortable" | {| class="wikitable sortable" | ||
+ | |+ Action syntax of HbbTV actions | ||
|- | |- | ||
! Syntax !! Example !! Since Version !! class="unsortable" | Description | ! Syntax !! Example !! Since Version !! class="unsortable" | Description | ||
Line 159: | Line 208: | ||
|| <code>video:broadcast:current</code> | || <code>video:broadcast:current</code> | ||
| data-sort-value=30|'''0.1.30''' | | data-sort-value=30|'''0.1.30''' | ||
− | || Plays the current broadcast channel. | + | || |
+ | Plays the current broadcast channel. | ||
|- | |- | ||
| <code>system:hbbtv:launch:{URL}</code> | | <code>system:hbbtv:launch:{URL}</code> | ||
|| <code>system:hbbtv:launch:http://msx.benzac.de/hbbtv.html</code> | || <code>system:hbbtv:launch:http://msx.benzac.de/hbbtv.html</code> | ||
| data-sort-value=30|'''0.1.30''' | | data-sort-value=30|'''0.1.30''' | ||
− | || Launches a new HbbTV application. The <code>{URL}</code> part must be replaced with an HTML page or an XML AIT URL. | + | || |
+ | Launches a new HbbTV application. The <code>{URL}</code> 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. | + | For more information about the HbbTV specification, please visit: https://www.hbbtv.org. |
== Server Actions == | == Server Actions == | ||
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). | 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 <code>Content-Type</code> header for all HTTP POST requests is set to <code>application/x-www-form-urlencoded</code> (instead of <code>application/json</code>) to ensure CORS support for simple services (by avoiding CORS preflight requests). Please ignore the <code>Content-Type</code> 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 <code>accurate:</code> prefix before <code>{URL}</code> to use the accurate headers (e.g. <code>execute:accurate:{URL}</code>, <code>execute:code:accurate:{URL}</code>, <code>execute:user:accurate:{URL}</code>, etc.).''' | + | '''Note: The <code>Content-Type</code> header for all HTTP POST requests is set to <code>application/x-www-form-urlencoded</code> (instead of <code>application/json</code>) to ensure CORS support for simple services (by avoiding CORS preflight requests). Please ignore the <code>Content-Type</code> 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 <code>accurate:</code> prefix before <code>{URL}</code> to use the accurate headers (e.g. <code>execute:accurate:{URL}</code>, <code>execute:code:accurate:{URL}</code>, <code>execute:user:accurate:{URL}</code>, etc.). Since version 0.1.90, it is also possible to execute multiple server actions at the same time by using a <code>service:</code> prefix (e.g. <code>execute:service:{URL}</code>, <code>execute:service:accurate:{URL}</code>, <code>execute:service:user:accurate:{URL}</code>, etc.). However, to detect errors and avoid overloading, the maximum number of parallel service actions is limited to 128.''' |
{| class="wikitable sortable" | {| class="wikitable sortable" | ||
+ | |+ Action syntax of server actions | ||
|- | |- | ||
! Syntax !! Example !! Since Version !! class="unsortable" | Description | ! Syntax !! Example !! Since Version !! class="unsortable" | Description | ||
Line 181: | Line 233: | ||
|| <code>execute:http://msx.benzac.de/services/echo.php</code> | || <code>execute:http://msx.benzac.de/services/echo.php</code> | ||
| data-sort-value=30|'''0.1.30''' | | data-sort-value=30|'''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 <code>{URL}</code> part must be replaced with your service URL. If the corresponding content item provides a <code>data</code> property, it is submitted as <code>data</code> property to your service. | + | || |
+ | Executes an action on server side and returns an action to be executed (e.g. to show a success/error message). The <code>{URL}</code> part must be replaced with your service URL. If the corresponding content item provides a <code>data</code> property, it is submitted as <code>data</code> property to your service. | ||
The returned action must be indicated as <code>action</code> property in the <code>data</code> property of a wrapped <code>response</code> object (i.e. in the <code>response.data.action</code> property). Optionally, an action-related <code>data</code> property (of type <code>object</code>) can also be indicated (i.e. in the <code>response.data.data property</code>). | The returned action must be indicated as <code>action</code> property in the <code>data</code> property of a wrapped <code>response</code> object (i.e. in the <code>response.data.action</code> property). Optionally, an action-related <code>data</code> property (of type <code>object</code>) can also be indicated (i.e. in the <code>response.data.data property</code>). | ||
Line 187: | Line 240: | ||
'''Note: If you return actions like <code>video:{URL}</code> or <code>audio:{URL}</code>, the corresponding content item properties (i.e. <code>playerLabel</code>, <code>background</code>, and <code>properties</code>) must be indicated in the action-related <code>data</code> property (i.e. <code>response.data.data</code> property) in order to be used.''' | '''Note: If you return actions like <code>video:{URL}</code> or <code>audio:{URL}</code>, the corresponding content item properties (i.e. <code>playerLabel</code>, <code>background</code>, and <code>properties</code>) must be indicated in the action-related <code>data</code> property (i.e. <code>response.data.data</code> property) in order to be used.''' | ||
− | Please see | + | Please see [[Responses]] for more information. |
|- | |- | ||
| <code>execute:code:{URL}</code> | | <code>execute:code:{URL}</code> | ||
|| <code>execute:code:http://msx.benzac.de/services/echo.php</code> | || <code>execute:code:http://msx.benzac.de/services/echo.php</code> | ||
| data-sort-value=30|'''0.1.30''' | | data-sort-value=30|'''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 <code>{URL}</code> part must be replaced with your service URL. If the corresponding content item provides a <code>data</code> property, it is submitted as <code>data</code> property to your service. The code is submitted as <code>code</code> property. | + | || |
+ | 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 <code>{URL}</code> part must be replaced with your service URL. If the corresponding content item provides a <code>data</code> property, it is submitted as <code>data</code> property to your service. The code is submitted as <code>code</code> property. | ||
If the corresponding content item provides a <code>data</code> property, it can be used to customize the code panel with following properties. | If the corresponding content item provides a <code>data</code> property, it can be used to customize the code panel with following properties. | ||
Line 206: | Line 260: | ||
'''Note: If you return actions like <code>video:{URL}</code> or <code>audio:{URL}</code>, the corresponding content item properties (i.e. <code>playerLabel</code>, <code>background</code>, and <code>properties</code>) must be indicated in the action-related <code>data</code> property (i.e. <code>response.data.data</code> property) in order to be used.''' | '''Note: If you return actions like <code>video:{URL}</code> or <code>audio:{URL}</code>, the corresponding content item properties (i.e. <code>playerLabel</code>, <code>background</code>, and <code>properties</code>) must be indicated in the action-related <code>data</code> property (i.e. <code>response.data.data</code> property) in order to be used.''' | ||
− | Please see | + | Please see [[Responses]] for more information. |
|- | |- | ||
| <code>execute:user:{URL}</code> | | <code>execute:user:{URL}</code> | ||
|| <code>execute:user:http://msx.benzac.de/services/echo.php</code> | || <code>execute:user:http://msx.benzac.de/services/echo.php</code> | ||
| data-sort-value=30|'''0.1.30''' | | data-sort-value=30|'''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 <code>execute:{URL}</code>, except that user credentials (e.g. cookies, authorization headers, etc.) are enabled for this request. Technically, this action sets the <code>withCredentials</code> flag for the <code>XMLHttpRequest</code> object to <code>true</code>. | + | || |
+ | 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 <code>execute:{URL}</code>, except that user credentials (e.g. cookies, authorization headers, etc.) are enabled for this request. Technically, this action sets the <code>withCredentials</code> flag for the <code>XMLHttpRequest</code> object to <code>true</code>. | ||
The <code>user:</code> prefix before <code>{URL}</code> can also be used inside the <code>data</code> property of a menu item and for following actions. | The <code>user:</code> prefix before <code>{URL}</code> can also be used inside the <code>data</code> property of a menu item and for following actions. | ||
Line 230: | Line 285: | ||
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). | 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). | ||
{| class="wikitable sortable" | {| class="wikitable sortable" | ||
+ | |+ Action syntax of extended actions | ||
|- | |- | ||
! Syntax !! Example !! Since Version !! class="unsortable" | Description | ! Syntax !! Example !! Since Version !! class="unsortable" | Description | ||
Line 236: | Line 292: | ||
|| <code>reload</code> | || <code>reload</code> | ||
| data-sort-value=58|'''0.1.58''' | | data-sort-value=58|'''0.1.58''' | ||
− | || Reloads the application. | + | || |
+ | Reloads the application. | ||
|- | |- | ||
| <code>reload:menu</code> | | <code>reload:menu</code> | ||
Line 243: | Line 300: | ||
|| Reloads the current menu data. | || Reloads the current menu data. | ||
− | '''Note: The menu data can only be reloaded if it has not been loaded via the | + | '''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 <code>reference</code> property. Since version 0.1.144, you can also replace (and reload) the menu data that has been loaded at startup or set via a data action by using the <code>replace:menu:{CONTENT_FLAG}:{REQUEST_ACTION}</code> action.''' |
|- | |- | ||
| <code>reload:content</code> | | <code>reload:content</code> | ||
|| <code>reload:content</code> | || <code>reload:content</code> | ||
| data-sort-value=58|'''0.1.58''' | | data-sort-value=58|'''0.1.58''' | ||
− | || Reloads the current content data. | + | || |
+ | Reloads the current content data. | ||
− | '''Note: The content data can only be reloaded if it has not been loaded via the | + | '''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 <code>reference</code> property. Since version 0.1.144, you can also replace (and reload) the content data that has been loaded at startup or set via a data action by using the <code>replace:content:{CONTENT_FLAG}:{REQUEST_ACTION}</code> action.''' |
|- | |- | ||
| <code>reload:panel</code> | | <code>reload:panel</code> | ||
|| <code>reload:panel</code> | || <code>reload:panel</code> | ||
| data-sort-value=58|'''0.1.58''' | | data-sort-value=58|'''0.1.58''' | ||
− | || Reloads the current panel content data. | + | || |
+ | 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.''' | + | '''Note: The panel content data can only be reloaded if it has not been set via a data action. Since version 0.1.144, you can replace (and reload) the panel content data that has been set via a data action by using the <code>replace:panel:{CONTENT_FLAG}:{REQUEST_ACTION}</code> action.''' |
|- | |- | ||
| <code>update:menu:{ID}</code> | | <code>update:menu:{ID}</code> | ||
|| <code>update:menu:menu_item_id</code> | || <code>update:menu:menu_item_id</code> | ||
| data-sort-value=58|'''0.1.58''' | | data-sort-value=58|'''0.1.58''' | ||
− | || Updates the data of a menu item. The <code>{ID}</code> part must be replaced with the menu item ID. The update data must be provided as <code>data</code> property by the corresponding content item. Following data properties can be updated. | + | || |
+ | Updates the data of a menu item. The <code>{ID}</code> part must be replaced with the menu item ID. The update data must be provided as <code>data</code> property by the corresponding content item. Following data properties can be updated. | ||
* <code>icon</code> | * <code>icon</code> | ||
+ | * <code>image</code> | ||
* <code>label</code> | * <code>label</code> | ||
+ | * <code>background</code> | ||
* <code>extensionIcon</code> | * <code>extensionIcon</code> | ||
* <code>extensionLabel</code> | * <code>extensionLabel</code> | ||
+ | * <code>lineColor</code> | ||
+ | * <code>options</code> | ||
− | '''Note: Only if the properties have been set (to a non <code>null</code> value) in the origin data, they can be updated.''' | + | '''Note: Only if the properties have been set (to a non <code>null</code> value) in the origin data, they can be updated. However, the <code>background</code> and <code>options</code> property can always be updated.''' |
− | Please see | + | Please see [[Menu Item Object]] for the data structure. |
|- | |- | ||
− | | <code>update: | + | | <code>update:content:{ID}</code> |
− | || <code>update: | + | || <code>update:content:content_item_id</code> |
| data-sort-value=58|'''0.1.58''' | | data-sort-value=58|'''0.1.58''' | ||
− | || Updates the data of a content item. The <code>{ID}</code> part must be replaced with the content item ID. The update data must be provided as <code>data</code> property by the corresponding content item. Following data properties can be updated. | + | || |
+ | Updates the data of a content item. The <code>{ID}</code> part must be replaced with the content item ID. The update data must be provided as <code>data</code> property by the corresponding content item. Following data properties can be updated. | ||
− | * color | + | * <code>color</code> |
− | * title | + | * <code>title</code> |
− | * titleHeader | + | * <code>titleHeader</code> |
− | * titleFooter | + | * <code>titleFooter</code> |
− | * label | + | * <code>label</code> |
− | * icon | + | * <code>icon</code> |
− | * headline | + | * <code>headline</code> |
− | * text | + | * <code>text</code> |
− | * tag | + | * <code>tag</code> |
− | * tagColor | + | * <code>tagColor</code> |
− | * badge | + | * <code>badge</code> |
− | * badgeColor | + | * <code>badgeColor</code> |
− | * progress | + | * <code>stamp</code> |
− | * progressColor | + | * <code>stampColor</code> |
− | * wrapperColor | + | * <code>progress</code> |
− | * image | + | * <code>progressColor</code> |
− | * extensionIcon | + | * <code>progressBackColor</code> |
− | * extensionLabel | + | * <code>wrapperColor</code> |
− | * live | + | * <code>image</code> |
− | * selection | + | * <code>extensionIcon</code> |
− | * options | + | * <code>extensionLabel</code> |
+ | * <code>live</code> | ||
+ | * <code>selection</code> | ||
+ | * <code>options</code> | ||
'''Note: Only if the properties have been set (to a non <code>null</code> value) in the origin data, they can be updated. However, the <code>live</code>, <code>selection</code>, and <code>options</code> property can always be updated.''' | '''Note: Only if the properties have been set (to a non <code>null</code> value) in the origin data, they can be updated. However, the <code>live</code>, <code>selection</code>, and <code>options</code> property can always be updated.''' | ||
− | Please see | + | Please see [[Content Item Object]] for the data structure. |
+ | |- | ||
+ | | <code>update:content:overlay:{ID}</code> | ||
+ | || <code>update:content:overlay:content_item_id</code> | ||
+ | | data-sort-value=110|'''0.1.110''' | ||
+ | || | ||
+ | Updates the data of a content overlay item. The <code>{ID}</code> part must be replaced with the content overlay item ID. The update data must be provided as <code>data</code> property by the corresponding content item. Please see action <code>update:content:{ID}</code> for more information about which data properties can be updated. | ||
+ | |- | ||
+ | | <code>update:content:underlay:{ID}</code> | ||
+ | || <code>update:content:underlay:content_item_id</code> | ||
+ | | data-sort-value=112|'''0.1.112''' | ||
+ | || | ||
+ | Updates the data of a content underlay item. The <code>{ID}</code> part must be replaced with the content underlay item ID. The update data must be provided as <code>data</code> property by the corresponding content item. Please see action <code>update:content:{ID}</code> for more information about which data properties can be updated. | ||
+ | |- | ||
+ | | <code>update:panel:{ID}</code> | ||
+ | || <code>update:panel:content_item_id</code> | ||
+ | | data-sort-value=58|'''0.1.58''' | ||
+ | || | ||
+ | Updates the data of a panel content item. The <code>{ID}</code> part must be replaced with the panel content item ID. The update data must be provided as <code>data</code> property by the corresponding content item. Please see action <code>update:content:{ID}</code> for more information about which data properties can be updated. | ||
+ | |- | ||
+ | | <code>update:panel:overlay:{ID}</code> | ||
+ | || <code>update:panel:overlay:content_item_id</code> | ||
+ | | data-sort-value=110|'''0.1.110''' | ||
+ | || | ||
+ | Updates the data of a panel content overlay item. The <code>{ID}</code> part must be replaced with the panel content overlay item ID. The update data must be provided as <code>data</code> property by the corresponding content item. Please see action <code>update:content:{ID}</code> for more information about which data properties can be updated. | ||
+ | |- | ||
+ | | <code>update:panel:underlay:{ID}</code> | ||
+ | || <code>update:panel:underlay:content_item_id</code> | ||
+ | | data-sort-value=112|'''0.1.112''' | ||
+ | || | ||
+ | Updates the data of a panel content underlay item. The <code>{ID}</code> part must be replaced with the panel content underlay item ID. The update data must be provided as <code>data</code> property by the corresponding content item. Please see action <code>update:content:{ID}</code> for more information about which data properties can be updated. | ||
+ | |- | ||
+ | | <code>data</code> | ||
+ | || <code>data</code> | ||
+ | | data-sort-value=58|'''0.1.58''' | ||
+ | || | ||
+ | This action can be used to execute multiple actions in a row. The actions must be provided as <code>actions</code> property (of type <code>array</code>) in the <code>data</code> property of the corresponding content item. Each action must be indicated as <code>object</code> and must provide an <code>action</code> property (of type <code>string</code>) and can optionally provide an action-related <code>data</code> property (of type <code>object</code>). | ||
+ | |||
+ | '''Note: If you use actions like <code>video:{URL}</code> or <code>audio:{URL}</code> with this syntax, the corresponding content item properties (i.e. <code>playerLabel</code>, <code>background</code>, and <code>properties</code>) must be indicated in the action-related <code>data</code> property in order to be used.''' | ||
+ | |- | ||
+ | | <code>[{ACTION}{{pipe}}{ACTION}{{pipe}}...]</code> | ||
+ | || <code>[reload:content{{pipe}}info:Action executed.]</code> | ||
+ | | data-sort-value=58|'''0.1.58''' | ||
+ | || | ||
+ | If an action starts with the character <code>[</code> and ends with the character <code>]</code>, you can use the character <code>{{pipe}}</code> to execute multiple actions in a row. The <code>{ACTION}</code> part must be replaced with any action. If the corresponding content item provides a <code>data</code> property, it is used for each action. If you want to use the <code>{{pipe}}</code> character within an action, please use the <code>{pipe}</code> keyword (e.g. <code>[reload:content{{pipe}}info:[P{pipe}I{pipe}P{pipe}E]]</code>). By the way, this syntax can also be used to perform a NOP (no operation) action by indicating an empty list (i.e. <code>[]</code>). | ||
+ | |||
+ | '''Note: If you use actions like <code>video:{URL}</code> or <code>audio:{URL}</code> with this syntax, the corresponding content item properties (i.e. <code>playerLabel</code>, <code>background</code>, and <code>properties</code>) must be indicated in the action-related <code>data</code> property in order to be used.''' | ||
|} | |} |
Latest revision as of 20:28, 11 April 2024
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]
Syntax | Example | Since Version | Description |
---|---|---|---|
video:{URL}
|
video:http://msx.benzac.de/media/video1.mp4
|
0.1.0 |
Plays a video. The |
audio:{URL}
|
audio:http://msx.benzac.de/media/audio1.mp3
|
0.1.0 |
Plays an audio. The |
image:{URL}
|
image:http://msx.benzac.de/img/bg1.jpg
|
0.1.0 |
Shows an image. The |
image:context
|
image:context
|
0.1.0 |
Shows an image by using the current context. The image URL must be provided as |
link:{URL}
|
link:http://msx.benzac.de/info/
|
0.1.0 |
Opens a link. The |
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 |
playlist:{URL}
|
playlist:http://msx.benzac.de/info/data/guide/videos.json
|
0.1.0 |
Loads a playlist without a corresponding content page. The Note: Please note that it is also possible to indicate request actions instead of URLs (e.g. |
playlist:data
|
playlist:data
|
0.1.0 |
Starts a playlist without a corresponding content page. The playlist data must be provided as Note: Please note that it is also possible to indicate the data inline as base64-encoded JSON (e.g. |
slideshow:{URL}
|
slideshow:http://msx.benzac.de/info/data/guide/images.json
|
0.1.0 |
Loads a slideshow without a corresponding content page. The Note: Please note that it is also possible to indicate request actions instead of URLs (e.g. |
slideshow:data
|
slideshow:data
|
0.1.0 |
Starts a slideshow without a corresponding content page. The playlist data must be provided as Note: Please note that it is also possible to indicate the data inline as base64-encoded JSON (e.g. |
menu:{URL}
|
menu:http://msx.benzac.de/info/data/guide/actions.json
|
0.1.0 |
Loads a menu. The Note: Please note that it is also possible to indicate request actions instead of URLs (e.g. |
menu:data
|
menu:data
|
0.1.0 |
Shows a menu. The menu data must be provided as Note: Please note that it is also possible to indicate the data inline as base64-encoded JSON (e.g. |
content:{URL}
|
content:http://msx.benzac.de/info/data/guide/videos.json
|
0.1.0 |
Loads a content page. The Note: Please note that it is also possible to indicate request actions instead of URLs (e.g. |
content:data
|
content:data
|
0.1.0 |
Shows a content page. The content data must be provided as Note: Please note that it is also possible to indicate the data inline as base64-encoded JSON (e.g. |
panel:{URL}
|
panel:http://msx.benzac.de/info/data/guide/panel.json
|
0.1.0 |
Loads a content page in a panel. The Note: Please note that it is also possible to indicate request actions instead of URLs (e.g. |
panel:data
|
panel:data
|
0.1.0 |
Shows a content page in a panel. The content data must be provided as Note: Please note that it is also possible to indicate the data inline as base64-encoded JSON (e.g. |
success:{TEXT}
|
success:This is a success message.
|
0.1.0 |
Shows a success message. The |
info:{TEXT}
|
info:This is an info message.
|
0.1.0 |
Shows an info message. The |
warn:{TEXT}
|
warn:This is a warning message.
|
0.1.0 |
Shows a warning message. The |
error:{TEXT}
|
error:This is an error message.
|
0.1.0 |
Shows an error message. The |
focus:{ID}
|
focus:content_item_id
|
0.1.0 |
Sets the focus to a specific item in the current context. The |
focus:index:{INDEX}
|
focus:index:0
|
0.1.0 |
Sets the focus to a specific item in the current context. The |
start
|
start
|
0.1.30 |
Sets up a new start parameter. The start parameter data must be provided as |
video:plugin:{URL}
|
video:plugin:http://msx.benzac.de/plugins/template.html
|
0.1.40 |
Plays a plugin video. The |
audio:plugin:{URL}
|
audio:plugin:http://msx.benzac.de/plugins/template.html
|
0.1.40 |
Plays a plugin audio. The |
HbbTV Actions[edit]
If you use the HbbTV version of Media Station X, you have additional actions available.
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 |
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.). Since version 0.1.90, it is also possible to execute multiple server actions at the same time by using a service:
prefix (e.g. execute:service:{URL}
, execute:service:accurate:{URL}
, execute:service:user:accurate:{URL}
, etc.). However, to detect errors and avoid overloading, the maximum number of parallel service actions is limited to 128.
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 The returned action must be indicated as Note: If you return actions like 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 If the corresponding content item provides a
The returned action must be indicated as Note: If you return actions like 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 The
If you use HTTP sessions and your server manages them via cookies, you should always add the 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 |
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).
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 |
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 |
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. Since version 0.1.144, you can replace (and reload) the panel content data that has been set via a data action by using the |
update:menu:{ID}
|
update:menu:menu_item_id
|
0.1.58 |
Updates the data of a menu item. The
Note: Only if the properties have been set (to a non 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
Note: Only if the properties have been set (to a non 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 |
update:content:underlay:{ID}
|
update:content:underlay:content_item_id
|
0.1.112 |
Updates the data of a content underlay item. The |
update:panel:{ID}
|
update:panel:content_item_id
|
0.1.58 |
Updates the data of a panel content item. The |
update:panel:overlay:{ID}
|
update:panel:overlay:content_item_id
|
0.1.110 |
Updates the data of a panel content overlay item. The |
update:panel:underlay:{ID}
|
update:panel:underlay:content_item_id
|
0.1.112 |
Updates the data of a panel content underlay item. The |
data
|
data
|
0.1.58 |
This action can be used to execute multiple actions in a row. The actions must be provided as Note: If you use actions like |
[{ACTION}|{ACTION}|...]
|
[reload:content|info:Action executed.]
|
0.1.58 |
If an action starts with the character Note: If you use actions like |