Difference between revisions of "Content Root Object"

From MSX - Wiki
Jump to navigation Jump to search
 
(47 intermediate revisions by the same user not shown)
Line 9: Line 9:
 
     "restore": true,
 
     "restore": true,
 
     "important": false,   
 
     "important": false,   
−
     "wrap": false,   
+
     "wrap": false,
−
    "transparent": false,
 
 
     "compress": false,
 
     "compress": false,
 +
    "preselect": false,
 +
    "refocus": 0,
 +
    "transparent": 0,
 
     "type": "pages",
 
     "type": "pages",
 
     "preload": "none",
 
     "preload": "none",
Line 23: Line 25:
 
     "header": null,
 
     "header": null,
 
     "footer": null,   
 
     "footer": null,   
 +
    "inserts": [],
 
     "overlay": null,   
 
     "overlay": null,   
 
     "underlay": null,
 
     "underlay": null,
 
     "action": null,
 
     "action": null,
 
     "data": null,
 
     "data": null,
 +
    "ready": null,
 
     "options": null,
 
     "options": null,
−
     "caption": "opt/menu"
+
     "caption": "opt/menu",
 +
    "captionUnderlay": -1
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 46: Line 51:
 
The reference of the content data. This property is only used if the content data is loaded at startup and can be used to load the actual data (i.e. non-startup related data) from another location. This allows you to keep the start content data more dynamic (e.g. by reloading it on the fly).
 
The reference of the content data. This property is only used if the content data is loaded at startup and can be used to load the actual data (i.e. non-startup related data) from another location. This allows you to keep the start content data more dynamic (e.g. by reloading it on the fly).
  
−
'''Note: Please note that most properties (e.g. <code>headline</code>, <code>items</code>, <code>pages</code>, <code>options</code>, etc.) are ignored if this property is set, because the corresponding values are provided by the  referenced data. Additionally, please note that it is also possible to indicate request actions instead of links (e.g. <code>"request:interaction:{DATA_ID}@{URL}"</code>).'''
+
'''Note: Please note that most properties (e.g. <code>headline</code>, <code>items</code>, <code>pages</code>, <code>options</code>, etc.) are ignored if this property is set, because the corresponding values are provided by the  referenced data. Additionally, please note that it is also possible to indicate request actions instead of URLs (e.g. <code>"request:interaction:{DATA_ID}@{URL}"</code>).'''
 
|-
 
|-
 
| <code>flag</code> || <code>string</code> || <code>null</code> || No || data-sort-value=120|'''0.1.120''' ||  
 
| <code>flag</code> || <code>string</code> || <code>null</code> || No || data-sort-value=120|'''0.1.120''' ||  
 
A custom content flag that can be evaluated by plugins and/or servers.
 
A custom content flag that can be evaluated by plugins and/or servers.
 +
 +
Since version '''0.1.144''', this flag can also be used to replace (and reload) the content data at runtime. For more information, please see [[Replace Action]].
 +
 +
Since version '''0.1.153''', this flag can also be used to refocus content items by using the <code>refocus</code> property.
 
|-
 
|-
 
| <code>reuse</code> || <code>boolean</code> || <code>true</code> || No || data-sort-value=0|0.1.0 ||  
 
| <code>reuse</code> || <code>boolean</code> || <code>true</code> || No || data-sort-value=0|0.1.0 ||  
Line 63: Line 72:
 
|-
 
|-
 
| <code>important</code> || <code>boolean</code> || <code>false</code> || No || data-sort-value=58|'''0.1.58''' ||  
 
| <code>important</code> || <code>boolean</code> || <code>false</code> || No || data-sort-value=58|'''0.1.58''' ||  
−
Indicates if the content data is important. This property can be used to enforce that the content headline is displayed.
+
Indicates if the content data is important. This property can be used to enforce that the content headline is displayed. This property has no effect if the content is displayed in a panel or the content is not loaded via a menu.
  
 
'''Note: The content headline is not displayed if the content is loaded via a menu, because in that case the menu item label is used as headline.'''
 
'''Note: The content headline is not displayed if the content is loaded via a menu, because in that case the menu item label is used as headline.'''
Line 72: Line 81:
 
'''Note: If the active content page has its own <code>wrap</code> property, this property is ignored.'''
 
'''Note: If the active content page has its own <code>wrap</code> property, this property is ignored.'''
 
|-
 
|-
−
| <code>transparent</code> || <code>boolean</code> || <code>false</code> || No || data-sort-value=120|'''0.1.120''' ||  
+
| <code>compress</code> || <code>boolean</code> || <code>false</code> || No || data-sort-value=123|'''0.1.123''' ||
 +
Indicates if the content is compressed by 25%. This property is part of the hidden features. For more information, please see [[Compress Property]].
 +
|-
 +
| <code>preselect</code> || <code>boolean</code> || <code>false</code> || No || data-sort-value=160|'''0.1.160''' ||
 +
Indicates if content pages and items should be preselected by executing the corresponding page and seletion actions before a content scroll animation. By default, these actions are executed after a content scroll animation.
 +
|-
 +
| <code>refocus</code> || <code>number</code>{{pipe}}<code>boolean</code> || <code>0</code> || No || data-sort-value=153|'''0.1.153''' ||
 +
Indicates if a content item should be refocused. The <code>flag</code> property is used to cache and restore the focus value.
 +
 
 +
* <code>0</code>{{pipe}}<code>false</code>: No content item is refocused.
 +
* <code>1</code>{{pipe}}<code>true</code>: The cached focused content item is refocused by using the item ID (and the item index as fallback).
 +
* <code>2</code>: The cached focused content item is refocused by using the item index only.
 +
 
 +
'''Note: To use this property, the <code>flag</code> property must also be set, otherwise this property is ignored. If a content item has a <code>focus</code> property set to <code>true</code>, the focus value is only cached but not restored.'''
 +
|-
 +
| <code>transparent</code> || <code>number</code>{{pipe}}<code>boolean</code> || <code>0</code> || No || data-sort-value=142|'''0.1.142''' ||  
 
Indicates if the content background is transparent. By default, the content background is set to a semi-transparent gray to darken the underlying video/image and make the content more visible. This property has no effect if the content is displayed in a panel.
 
Indicates if the content background is transparent. By default, the content background is set to a semi-transparent gray to darken the underlying video/image and make the content more visible. This property has no effect if the content is displayed in a panel.
 +
 +
* <code>0</code>{{pipe}}<code>false</code>: The content background is not transparent.
 +
* <code>1</code>{{pipe}}<code>true</code>: The content background is transparent.
 +
* <code>2</code>: The content background is only transparent if no video/audio is active or the active video/audio has set the extended property <code>"control:transparent"</code> to <code>"true"</code>. For more information, please see [[Extended Properties]].
  
 
'''Note: If the active content page has its own <code>transparent</code> property, this property is ignored.'''
 
'''Note: If the active content page has its own <code>transparent</code> property, this property is ignored.'''
−
|-
 
−
| <code>compress</code> || <code>boolean</code> || <code>false</code> || No || data-sort-value=123|'''0.1.123''' ||
 
−
Indicates if the content is compressed by 25%. This property is part of the hidden features. For more information, please see [[Compress Property]].
 
 
|-
 
|-
 
| <code>type</code> || <code>string</code> || <code>"pages"</code> || No || data-sort-value=0|0.1.0 ||  
 
| <code>type</code> || <code>string</code> || <code>"pages"</code> || No || data-sort-value=0|0.1.0 ||  
Line 103: Line 128:
 
'''Note: This property has no effect if the content is loaded via a menu, because in that case the menu item label is used as headline. Since version 0.1.58, you can set the property <code>important</code> to <code>true</code> to enforce that this property is used.'''
 
'''Note: This property has no effect if the content is loaded via a menu, because in that case the menu item label is used as headline. Since version 0.1.58, you can set the property <code>important</code> to <code>true</code> to enforce that this property is used.'''
  
−
This property supports inline expressions. For more information, please see [[Inline Expressions]].
+
This property supports [[Inline Expressions]].
 
|-
 
|-
 
| <code>background</code> || <code>string</code> || <code>null</code> || No || data-sort-value=0|0.1.0 ||  
 
| <code>background</code> || <code>string</code> || <code>null</code> || No || data-sort-value=0|0.1.0 ||  
Line 110: Line 135:
 
| <code>extension</code> || <code>string</code> || <code>null</code> || No || data-sort-value=82|'''0.1.82''' ||  
 
| <code>extension</code> || <code>string</code> || <code>null</code> || No || data-sort-value=82|'''0.1.82''' ||  
 
The extension of the content screen. This property can be used to display a small label in the upper right corner of the content screen (e.g. to show the logged in user, the current date/time, etc.).
 
The extension of the content screen. This property can be used to display a small label in the upper right corner of the content screen (e.g. to show the logged in user, the current date/time, etc.).
−
 
+
This property supports [[Inline Expressions]] and [[Live Inline Expressions]].
−
This property supports inline expressions and live inline expressions. For more information about the inline expressions, please see [[Inline Expressions]]. For more information about the live inline expressions, please see [[Live Inline Expressions]].
 
 
|-
 
|-
 
| <code>dictionary</code> || <code>string</code> || <code>null</code> || No || data-sort-value=120|'''0.1.120''' ||  
 
| <code>dictionary</code> || <code>string</code> || <code>null</code> || No || data-sort-value=120|'''0.1.120''' ||  
−
A link to a dictionary file. This property is only used if the content data is loaded at startup and can be used to setup a dictionary. A dictionary can be used to translate the application user interface.  
+
A URL to a dictionary file. This property is only used if the content data is loaded at startup and can be used to setup a dictionary. A dictionary can be used to translate the application user interface.  
 
For more information, please see [[Dictionary Structure]].
 
For more information, please see [[Dictionary Structure]].
 
|-
 
|-
Line 125: Line 149:
 
An array of content items. Please see [[Content Item Object]] for the data structure. This property is mandatory if the content items should be automatically created and positioned.
 
An array of content items. Please see [[Content Item Object]] for the data structure. This property is mandatory if the content items should be automatically created and positioned.
  
−
'''Note: Templated content items only have to specify the relevant properties. The other properties are copied from the <code>template</code> object. To use this property, the template property must also be set, otherwise this property is ignored.'''
+
'''Note: Templated content items only have to specify the relevant properties. The other properties are copied from the <code>template</code> object. To use this property, the <code>template</code> property must also be set, otherwise this property is ignored.'''
 
|-
 
|-
 
| <code>pages</code> || <code>array</code> || <code>null</code> || '''Only for non-templated items''' || data-sort-value=0|0.1.0 ||  
 
| <code>pages</code> || <code>array</code> || <code>null</code> || '''Only for non-templated items''' || data-sort-value=0|0.1.0 ||  
Line 139: Line 163:
 
| <code>footer</code> || <code>object</code> || <code>null</code> || No || data-sort-value=53|'''0.1.53''' ||  
 
| <code>footer</code> || <code>object</code> || <code>null</code> || No || data-sort-value=53|'''0.1.53''' ||  
 
An individual footer page for templated content items. Please see [[Content Page Object]] for the data structure.
 
An individual footer page for templated content items. Please see [[Content Page Object]] for the data structure.
 +
 +
'''Note: To use this property, the <code>template</code> and <code>items</code> property must also be set, otherwise this property is ignored.'''
 +
|-
 +
| <code>inserts</code> || <code>array</code> || <code>null</code> || No || data-sort-value=156|'''0.1.156''' ||
 +
An array of individual insert pages for templated content items. Please see [[Content Page Object]] for the data structure and the <code>position</code> property available there for more information.
  
 
'''Note: To use this property, the <code>template</code> and <code>items</code> property must also be set, otherwise this property is ignored.'''
 
'''Note: To use this property, the <code>template</code> and <code>items</code> property must also be set, otherwise this property is ignored.'''
Line 157: Line 186:
 
| <code>data</code> || <code>object</code> || <code>null</code> || No || data-sort-value=0|0.1.0 ||  
 
| <code>data</code> || <code>object</code> || <code>null</code> || No || data-sort-value=0|0.1.0 ||  
 
The additional data of the start action that is used if the action is executed. This property is part of the hidden features. For more information, please see [[Start Action]].
 
The additional data of the start action that is used if the action is executed. This property is part of the hidden features. For more information, please see [[Start Action]].
 +
|-
 +
| <code>ready</code> || <code>object</code> || <code>null</code> || No || data-sort-value=142|'''0.1.142''' ||
 +
A special ready object that can contain an <code>action</code> property (of type <code>string</code>) and an action-related <code>data</code> property (of type <code>object</code>). It can be used to execute an action when the content is ready. Please see [[Internal Actions]] for possible values.
 
|-
 
|-
 
| <code>options</code> || <code>object</code> || <code>null</code> || No || data-sort-value=120|'''0.1.120''' ||  
 
| <code>options</code> || <code>object</code> || <code>null</code> || No || data-sort-value=120|'''0.1.120''' ||  
 
A special page object that is displayed in a panel if a content item is selected and the menu button is pressed. The availability of options for the current selected item is indicated in the lower right corner of the content screen. This property is ignored if the content is displayed in a panel. Please see [[Content Page Object]] for the data structure.
 
A special page object that is displayed in a panel if a content item is selected and the menu button is pressed. The availability of options for the current selected item is indicated in the lower right corner of the content screen. This property is ignored if the content is displayed in a panel. Please see [[Content Page Object]] for the data structure.
  
−
Since version '''0.1.130''', you can also set a content root object as options. Please see [[#top|Content Root Object]] for the data structure.
+
Since version '''0.1.130''', you can also set a [[#top|Content Root Object]] as options.
  
 
'''Note: If the active content page or the selected content item has its own <code>options</code> property, this property is ignored.'''
 
'''Note: If the active content page or the selected content item has its own <code>options</code> property, this property is ignored.'''
Line 167: Line 199:
 
| <code>caption</code> || <code>string</code> || <code>"opt/menu"</code> || No || data-sort-value=130|'''0.1.130''' ||  
 
| <code>caption</code> || <code>string</code> || <code>"opt/menu"</code> || No || data-sort-value=130|'''0.1.130''' ||  
 
This property is only used if the content data is set as <code>options</code> property and can be used to set a custom options caption (indicated in the lower right corner of the content screen).
 
This property is only used if the content data is set as <code>options</code> property and can be used to set a custom options caption (indicated in the lower right corner of the content screen).
 +
This property supports [[Inline Expressions]].
 +
|-
 +
| <code>captionUnderlay</code> || <code>number</code> || <code>-1</code> || No || data-sort-value=153|'''0.1.153''' ||
 +
The underlay of the content caption. This property can be used to explicitly set or remove the underlay of the content caption. The underlay is used to darken the lower part of the screen to make the caption more visible. By default, the underlay is used if a content list has overflowing items (i.e. content items are under the caption).
 +
 +
* <code>-1</code>: Automatically set/remove underlay.
 +
* <code>0</code>: Remove underlay.
 +
* <code>1</code>: Set underlay.
  
−
This property supports inline expressions. For more information, please see [[Inline Expressions]].
+
'''Note: If the active content page has set its own <code>captionUnderlay</code> property to <code>0</code> or <code>1</code>, this property is ignored.'''
 
|}
 
|}
  
Line 176: Line 216:
 
* [[Compress Property]]
 
* [[Compress Property]]
 
* [[Option Shortcut]]
 
* [[Option Shortcut]]
 +
* [[Replace Action]]
  
 
== See also ==
 
== See also ==

Latest revision as of 14:30, 2 October 2024

{  
    "name": "Content Name",
    "version": "1.0.0", 
    "reference": "http://link.to.content",
    "flag": "content_flag",
    "reuse": true,
    "cache": true,    
    "restore": true,
    "important": false,  
    "wrap": false,
    "compress": false,
    "preselect": false,
    "refocus": 0,
    "transparent": 0,
    "type": "pages",
    "preload": "none",
    "headline": "Content Headline", 
    "background": "http://link.to.image",
    "extension": "Content Extension",
    "dictionary": "http://link.to.dictionary",
    "template": null,
    "items": [],    
    "pages": [],
    "header": null,
    "footer": null,  
    "inserts": [],
    "overlay": null,  
    "underlay": null,
    "action": null,
    "data": null,
    "ready": null,
    "options": null,
    "caption": "opt/menu",
    "captionUnderlay": -1
}
Property syntax of content root object
Property Type Default Value Mandatory Since Version Description
name string null No 0.1.0

The name of the content. This property is only used if the content data is loaded at startup and can be used to set the content name. This value is displayed in the about panel of the Media Station X application.

version string null No 0.1.0

The version of the content. This property is only used if the content data is loaded at startup and can be used to add a content version. This value is displayed in the about panel of the Media Station X application.

reference string null No 0.1.134

The reference of the content data. This property is only used if the content data is loaded at startup and can be used to load the actual data (i.e. non-startup related data) from another location. This allows you to keep the start content data more dynamic (e.g. by reloading it on the fly).

Note: Please note that most properties (e.g. headline, items, pages, options, etc.) are ignored if this property is set, because the corresponding values are provided by the referenced data. Additionally, please note that it is also possible to indicate request actions instead of URLs (e.g. "request:interaction:{DATA_ID}@{URL}").

flag string null No 0.1.120

A custom content flag that can be evaluated by plugins and/or servers.

Since version 0.1.144, this flag can also be used to replace (and reload) the content data at runtime. For more information, please see Replace Action.

Since version 0.1.153, this flag can also be used to refocus content items by using the refocus property.

reuse boolean true No 0.1.0

Indicates if the content data can be reused. If this property is set to false, the content data is recreated each time it is displayed.

cache boolean true No 0.1.58

Indicates if the content data is being cached. This property can be used to disable the cache feature.

restore boolean true No 0.1.120

Indicates if the content data is restorable. If this property is set to false, the content data is not restored when the application returns from a link action. This property has no effect if the content is displayed in a panel.

Note: If the content is loaded via a menu and the menu data has set the restore property to false, this property is ignored.

important boolean false No 0.1.58

Indicates if the content data is important. This property can be used to enforce that the content headline is displayed. This property has no effect if the content is displayed in a panel or the content is not loaded via a menu.

Note: The content headline is not displayed if the content is loaded via a menu, because in that case the menu item label is used as headline.

wrap boolean false No 0.1.102

Indicates if the content data is wrapped. If this property is set to true, a corresponding menu can not be entered by using the navigation keys (i.e. left and right key). This property has no effect if the content is displayed in a panel or the content is not loaded via a menu.

Note: If the active content page has its own wrap property, this property is ignored.

compress boolean false No 0.1.123

Indicates if the content is compressed by 25%. This property is part of the hidden features. For more information, please see Compress Property.

preselect boolean false No 0.1.160

Indicates if content pages and items should be preselected by executing the corresponding page and seletion actions before a content scroll animation. By default, these actions are executed after a content scroll animation.

refocus number|boolean 0 No 0.1.153

Indicates if a content item should be refocused. The flag property is used to cache and restore the focus value.

  • 0|false: No content item is refocused.
  • 1|true: The cached focused content item is refocused by using the item ID (and the item index as fallback).
  • 2: The cached focused content item is refocused by using the item index only.

Note: To use this property, the flag property must also be set, otherwise this property is ignored. If a content item has a focus property set to true, the focus value is only cached but not restored.

transparent number|boolean 0 No 0.1.142

Indicates if the content background is transparent. By default, the content background is set to a semi-transparent gray to darken the underlying video/image and make the content more visible. This property has no effect if the content is displayed in a panel.

  • 0|false: The content background is not transparent.
  • 1|true: The content background is transparent.
  • 2: The content background is only transparent if no video/audio is active or the active video/audio has set the extended property "control:transparent" to "true". For more information, please see Extended Properties.

Note: If the active content page has its own transparent property, this property is ignored.

type string "pages" No 0.1.0

The type of the content items.

  • "pages": The content items are displayed as pages in horizontal direction.
  • "list": The content items are displayed as list in vertical direction.

Note: If the "list" type is used, content pages are stacked (i.e. vertical gaps between content pages are removed). This property has no effect if the content is displayed in a panel, because panels always use the "list" type.

preload string "none" No 0.1.92

The preload mode of the content pages (available for type "pages" and "list"). This property can be used to preload the next and/or previous visible page (e.g. to preload images, to pre-perform live updates, etc.). By default, this feature is disabled.

Note: Please use this feature wisely, because preloading pages can decrease the performance.

  • "none": Preload no pages.
  • "next": Preload the next visible page.
  • "prev": Preload the previous visible page.
  • "full": Preload the next and previous visible page.
headline string null No 0.1.0

The headline of the content.

Note: This property has no effect if the content is loaded via a menu, because in that case the menu item label is used as headline. Since version 0.1.58, you can set the property important to true to enforce that this property is used.

This property supports Inline Expressions.

background string null No 0.1.0

The background image that is used if no other background is set at lower levels. If the content data is loaded at startup, this background image is used as default.

extension string null No 0.1.82

The extension of the content screen. This property can be used to display a small label in the upper right corner of the content screen (e.g. to show the logged in user, the current date/time, etc.). This property supports Inline Expressions and Live Inline Expressions.

dictionary string null No 0.1.120

A URL to a dictionary file. This property is only used if the content data is loaded at startup and can be used to setup a dictionary. A dictionary can be used to translate the application user interface. For more information, please see Dictionary Structure.

template object null Only for templated items 0.1.0

The template object to automatically create and position content items. Please see Content Item Object for the data structure. This property is mandatory if the content items should be automatically created and positioned.

Note: Templated content items have all the same size and can be used to quickly create lists without having to deal with grid positions. To use this property, the items property must also be set, otherwise this property is ignored.

items array null Only for templated items 0.1.0

An array of content items. Please see Content Item Object for the data structure. This property is mandatory if the content items should be automatically created and positioned.

Note: Templated content items only have to specify the relevant properties. The other properties are copied from the template object. To use this property, the template property must also be set, otherwise this property is ignored.

pages array null Only for non-templated items 0.1.0

An array of content pages. Please see Content Page Object for the data structure. This property is mandatory if the content items should be manually created and positioned.

Note: This property is ignored if a template and items property is set.

header object null No 0.1.53

An individual header page for templated content items. Please see Content Page Object for the data structure.

Note: To use this property, the template and items property must also be set, otherwise this property is ignored.

footer object null No 0.1.53

An individual footer page for templated content items. Please see Content Page Object for the data structure.

Note: To use this property, the template and items property must also be set, otherwise this property is ignored.

inserts array null No 0.1.156

An array of individual insert pages for templated content items. Please see Content Page Object for the data structure and the position property available there for more information.

Note: To use this property, the template and items property must also be set, otherwise this property is ignored.

overlay object null No 0.1.110

An independent overlay page that is displayed over each content page. Please see Content Page Object for the data structure.

Note: For the overlay page, only items of type "space" are allowed. It is possible to hide the overlay page if the active content page has set the important property to true.

underlay object null No 0.1.112

An independent underlay page that is displayed under each content page. Please see Content Page Object for the data structure.

Note: For the underlay page, only items of type "space" are allowed. It is possible to hide the underlay page if the active content page has set the important property to true.

action string null No 0.1.0

The start action that is executed if the content data is loaded at startup. This property is part of the hidden features. For more information, please see Start Action.

data object null No 0.1.0

The additional data of the start action that is used if the action is executed. This property is part of the hidden features. For more information, please see Start Action.

ready object null No 0.1.142

A special ready object that can contain an action property (of type string) and an action-related data property (of type object). It can be used to execute an action when the content is ready. Please see Internal Actions for possible values.

options object null No 0.1.120

A special page object that is displayed in a panel if a content item is selected and the menu button is pressed. The availability of options for the current selected item is indicated in the lower right corner of the content screen. This property is ignored if the content is displayed in a panel. Please see Content Page Object for the data structure.

Since version 0.1.130, you can also set a Content Root Object as options.

Note: If the active content page or the selected content item has its own options property, this property is ignored.

caption string "opt/menu" No 0.1.130

This property is only used if the content data is set as options property and can be used to set a custom options caption (indicated in the lower right corner of the content screen). This property supports Inline Expressions.

captionUnderlay number -1 No 0.1.153

The underlay of the content caption. This property can be used to explicitly set or remove the underlay of the content caption. The underlay is used to darken the lower part of the screen to make the caption more visible. By default, the underlay is used if a content list has overflowing items (i.e. content items are under the caption).

  • -1: Automatically set/remove underlay.
  • 0: Remove underlay.
  • 1: Set underlay.

Note: If the active content page has set its own captionUnderlay property to 0 or 1, this property is ignored.

Related Hidden Features[edit]

See also[edit]

Retrieved from "https://msx.benzac.de/wiki/index.php?title=Content_Root_Object&oldid=3541"