Event-handling is a core concept when building interactivity in menu-pages. An event-handler consists of: a trigger, one or more actions and parameters to the actions. This is what enables you to for example open a new page when a button is selected on the screen.
The event-handler editor is available both in the page level settings window and in the element settings window. Handlers can be set up on both levels, but element handlers will proceed page handlers. Once a handler has handled an event, that event is blocked for further processing. Eg if an element has a handler for the keypress 1 and the key is pressed while the element is in the highlighted state, then any handler listening for this keypress on the page level will not be invoked.
To see what elements and pages emit what events, consult the The Page & Elements document.
¶ The event handler editor
The event handler editor lets you add, modify and delete triggers and their corresponding handlers.
- A Trigger is set up to run when some event occurs.
- An Action is run when a trigger is set off.
- Parameters are passed to Actions and can be based on the element that fired the initial event(eg ListItems).
All actions have a defined set of parameters supported. Note that these parameters can be templated, allowing the implementation of dynamic services.
¶ Actions
Here follows a list of all available actions:
¶ Only available on Elements
¶ Highlight the last active entry
Attempts to highlight the last entry that was highlighted prior to highlighting this entry. This is useful for stepping back in a configuration where multiple elements navigate to the same element.
¶ Run and action parsed from data-source item
Advanced feature
Run an action based on the actionID parsed out from a property.
¶ Update a list-elements data-source
Advanced feature
Update the data-source and data-source parameters of a list-element on the page.
¶ Only available on Pages
¶ Hide elements after a duration until next keypress
Define a list of elements that should auto-hide after a duration of no key-inputs. Any key-input will display the elements again.
Parameters:
duration - seconds that the items should be visible after last keypress.
targets - items to apply auto-hide on.
¶ Close page after a duration of inactivity
A given number of seconds after the last keypress, the page will be closed. PS A root-level page cannot be closed(eg main menu, TV-channels etc)
Parameters:
duration - seconds that the items should be visible after last keypress.
¶ Gradually increase audio volume
Used to slowly fade in audio, typically for wake-up pages.
Parameters:
From-vol - the volume to start the fade-in from.
To-vol - the volume to stop the fade-in at.
Stop-vol - the volume to set when a key is pressed and fade-in is aborted.
¶ Highlight the default element in page
Will highlight the element that is set as the default highlighted element on the page.
Parameters:
None
¶ Start recurring service request
To be used in combination with the "Every time the page is displayed" trigger.
This will perform the configured request to the configured service at a given interval.
A typical use example is when a client wants to hold on to an allocated service that requires a keep-alive type message from the client. Used in the Stream-Allocation service.
The minimum interval used in the screen application is 30 seconds, but it's recommended to use higher values.
Parameters:
Interval - the interval on which requests are placed(in seconds).
TV-Service - the service to request.
Method - HTTP request type: GET, POST, PUT or DELETE.
Item ID(optional) - The ID of the resource. Used by GET, PUT and DELETE.
Payload(optional) - JSON data. Only for PUT and POST methods.
¶ Available on both Page and Element level
¶ Highlight menu entry
Highlights another element on the page. Elements are identified by their name. Highlighting an element causes the currently highlighted element to lose highlight state.
Parameters:
Target - The label of the element to highlight.
¶ Filter data in store
Set a filter on the data of a defined element.
Parameters:
Target - the element to apply the filter on.
key - the key to use for filtering.
val - the value that key must hold to pass the filter.NOTE Setting an empty value or the value null will clear the filter.
¶ Start a native Smart-TV application
Start a native application on the TV if available. Different vendors/platforms require different app identifiers.
Parameters:
webos - the LG WebOS ID
netcast - the LG NetCast ID
orsay - the Samsung Orsay ID
tizen - the Samsung Tizen ID
android - the Android IDBrowser startpage - DEPRECATED used to pass a startpage to the built-in web-browser. This string will be used for all the different platforms, if supported. The string can be templated.
App Parameters - A set of key/values that can be passed to the native app as start-up params. How these are applied is up to the TV integration.
A list of built-in applications in various TV-platforms can be found here.
¶ Open page
Opens another page on your site.
Parameters:
MenuPageID - select the page to open.
Parameters - page parameters to pass to the new page. Can be templated
Replace - enable this to remove the parent page once the new page is loaded. Pages operate as a stack, so closing the new page will then revert to the next page in the stack. You cannot close the root page(MainMenu)
¶ Update the content/CSS of an item
Update the content and/or CSS of another item. Using this action you can totally change the content(including content-type) of another item. This changes the normal Content and CSS for that element, NOT the highlighted ones. CSS is applied to the DOM element which means it is the highest priority and will overwrite any lower priority CSS styles.
Parameters:
Target - the label of the element to modify.
Content - the new content definition.
CSS - the new CSS definition.
¶ Clear markup of an item
Clears the content of an item using an emtyp data file of type markup. Does NOT alter CSS.
Parameters:
Target - the label of the element to clear.
¶ Add or remove CSS classes on an item
Add or remove(two separate actions) CSS classes on a target.
Parameters:
Target - the label of the element to modify.
Classes - the classes to add or remove(separated by space).
¶ Open system menu
Open one of the pages as defined in the TVs running configuration.
Parameters:
MenuID - one of the pre-defined menu-types: Main, TV-channels, Full EPG, AudioLanguages, SubtitleLanguages, Welcome, External Inputs.
¶ HTTP request
Initiate a HTTP request to a defined URL. NOTE using relative URLs here(not starting with http: or https:) will cause requests to go to the system and appropriate authentication headers are set. In this case the defined headers are ignored.
Parameters:
URL - the target URL. Can be templated
HTTP-Method - GET, PUT, POST or DELETE
Payload - the payload to send(if applicable for the selected method). Can be templated
Close on complete - Can be set to close the current page once the request completes regardless of success or failure.
Headers - special HTTP headers to set in the request. The values can be templated(eg you can add roomNumer by {{settings.locationName}}).
New page parameters - page parameters to pass to the success/error page to be opened.
Open page on success - open a defined page if the HTTP request returns 2xx.
Open page on error - open a defined page if the HTTP request returns non-2xx.
¶ Create item in service
Create a new item in a pre-defined TV-service
Parameters:
Payload - JSON data.
New page parameters - page parameters to pass to the success/error page to be opened.
Open page on success - open a defined page if the HTTP request returns 2xx.
Open page on error - open a defined page if the HTTP request returns non-2xx.
¶ Update item in service
Update an exiting item in a pre-defined TV-service
Parameters:
Payload - JSON data
New page parameters - page parameters to pass to the success/error page to be opened.
Open page on success - open a defined page if the HTTP request returns 2xx.
Open page on error - open a defined page if the HTTP request returns non-2xx.
¶ Delete item in service
Delete an exiting item in a pre-defined TV-service
Parameters:
Item ID - the ID of the item to delete.
New page parameters - page parameters to pass to the success/error page to be opened.
Open page on success - open a defined page if the HTTP request returns 2xx.
Open page on error - open a defined page if the HTTP request returns non-2xx.
¶ Forward keypress to another item
Forward a keypress event to an element that is not in the highlight state.
Parameters:
Target - the element to forward the event to.
¶ Close this page
Close the current page. This will render and activate the next page in the display stack.
¶ Run built-in function
Run a pre-defined function on the TV. This is a "meta" action for handling various management functions without building a specific action per function.
Parameters:
function - a function from a pre-defined list of available functions: setSubtitleTrack, setAudioTrack, setExternalInput, setLanguage, openServiceMenu, tuneChannelId, powerOff, reboot.
arguments - arguments differ based on the function selected. Can be templated
¶ Trig the selection event on another item
Run the selection event on another element.
Parameters:
Target - the element to trig the selection on
¶ Load another page after a given duration
Useful for displaying intermittent pages. If set on the page load trigger, the page will then display for the given duration and then open a new page.
Parameters:
MenuPageID - the menupage to load. Can be templated
duration - the time to wait in seconds before loading.
params - page parameters. can be templated
replace - enable to close current page when the new page is loaded.
¶ Tune TV player to a media URL
Tune to a media URL
Parameters:
media URL - the media URL to tune to. Media URLs are described here
¶ Tune to a media channel UUID
Tune to a given TV-channel. The channel must be part of the TVs channel-table.
Parameters:
uuid - the UUID of the channel to tune.
¶ Tune to a media channel
REDUNDANT?
Parameters:
TODO
¶ Pause global media playback
Pauses the current playing TV-media if possible. As a main rule, only web-based playback can be paused.
¶ Resume global media playback
Resumes the current paused TV-media if possible. As a main rule, only web-based playback can be paused.
¶ Toggle resume/pause global media playback
Toggles pause/resume on the current TV-media. As a main rule, only web-based playback can be paused.
¶ Stop global media playback
Stops playback of any TV-media.
¶ Pause an element's media playback
Pauses the current playing media in a defined element if possible. Only spesific element types support this.
¶ Resume an element's media playback
Start/resumes playback of a defined element's media. Only spesific element types support this.
¶ Toggle an element's media playback
Toggles pause/resumes of playback on a defined element's media. Only spesific element types support this.
¶ Toggle an element's media playback
Updates the mediaID set on a spesific element. Only spesific element types support this.
Parameters:
MediaID - the new mediaID to set on the element. Will trigger current playack to stop and new item will start playing if the element is configured for auto-play.
¶ Set global CSS theme class(es)
Applies one or more outer CCS classes on the main view of the application. Can be used for theme-selection. These classes can then be matched in CSS configurations of elements and pages.
Parameters:
classes - the class(es) to apply.
¶ Start chromecast pairing
When using a display with built-in casting capabilities, this action will trigger the display of the cast pairing screen.
¶ Basic navigation
To allow for maximum flexibility in the system, you will have to build all navigation paths up by adding event handlers. A typical handler for navigation on an element is to add something like this:
Here we say that when the key right is pressed(and the current element is in the highlight state - we will not receive this event if not), the action to take is to highlight a page element. The page element to highlight is defined as a parameter to the action called Target.
Highlighting will ensure that a new element is highlighted and that the current element loses highlight. This also switches over CSS classes and, potentially, content for the affected elements, so that the visual confirmation for the end user is immediate.
Typically, an opposing handler will be added in the target element, causing the current element to be highlighted when the "left" key is pressed. This would then build a complete navigation path between the elements.
NOTE
To ensure proper navigation, there must always be a navigation path from an element that is targeted for highlighting. If not, the user is stuck at that element.
¶ The navigation helper
Since the concept of adding handlers that highlight other elements on the up, down, left and right keypresses is so commonly applied to elements, there is a helper available to quickly add these eventhandlers. This is brought up by clicking the crossing arrows icon on a highlighted element:
This brings up the navigation helper:
Using this helper, you can click on the box next to the target arrow in the helper window to activate it for selection. Then you click the target element that is to be highlighted by the current directional key.