Chapter 6. Application

The static class KONtx.application is a structure for applications. In general one app is one application, though the structure can support multiple simultaneous applications. The application class provides an environment that manages communication between the Engine and the app.

KONtx.application

a structure to manage communication with the Engine

The KONtx.application class manages event communication between the KONtx Framework and the application engine (the "Engine"). Events from the Engine are received by the KONtx.application class and re-fired as KONtx.system.Event types. You can subscribe to events coming from the Engine through the subscribeTo(KONtx.application) method and send events to the Engine through the KONtx.HostEventManager.send() method.

Example

KONtx.application Event Handling

The following table defines the events you can subscribe to through KONtx.application. Events whose event classes are both HostEvent and Framework indicate that these events are captured and then re-thrown by the KONtx.application class.

Handler Name

Event Class

Received By

Description

getSnippetConfs

HostEvent, Framework

app

Gathers bookmark metadata. The KONtx.application manager captures this Host event and refires it as a Framework event.

getProfileSnippetConfs

Framework

app

Gathers bookmark metadata that is specific to a profile. Called after onApplicationStartup and onLoadProfile events.

onActivateBackButton

Framework

app

The back button in the sidebar has been activated.

onActivateFavButton

Framework

app

The edit-bookmarks button in the sidebar has been activated.

onActivateHomeButton

Framework

app

The home button in the sidebar has been activated.

onActivateSettingsButton

Framework

app

The settings button in the sidebar has been activated.

onActivateSnippet

HostEvent, Framework

app

The user launches a bookmark. The KONtx.application manager captures this Host event and refires it as a Framework event.

onApplicationShutdown

Framework

app

The app is closing down.

onApplicationStartup

Framework

app

The app’s main file is loaded.

onColorKeyPress

Framework

app

RED, GREEN, YELLOW, BLUE keypress from the Engine. Fired after the Host event keydown is received from the Engine. Available in KONtx 1.2 and above.

onCountryCodeChanged

Framework

app

Indicates the country code has changed. Each time a Framework event is fired, the KONtx.application manager calls specialSettings.get('countryCode') to check the country code. If the country code is not the same as in previous checks, the onCountryCodeChanged Framework event is fired.

onDialogCancelled

HostEvent, Framework

app

Dialog has been cancelled. The KONtx.application manager captures this Host event and refires it as a Framework event.

onDialogDone

HostEvent, Framework

app

Dialog has been completed. The KONtx.application manager captures this Host event and refires it as a Framework event.

onHideView

HostEvent,Framework

app

The app view is no longer visible. The KONtx.application manager captures this Host event and refires it as a Framework event.

onLoadProfile

HostEvent, Framework

app

The app is newly initialized or switching profiles. The KONtx.application manager captures this Host event and refires it as a Framework event. This handler also fires the getProfileSnippetConfs Framework event.

onLoadView

HostEvent,Framework

app

The Engine has loaded the app’s XML. The KONtx.application manager captures this Host event and refires it as a Framework event.

onNetworkConnectionDisconnect

Framework

app

Event fired when the network connection is lost. If the app needs the network, the network status icons are displayed by sending the setIcons event to the Engine and the “No Network” dialog is displayed.

onNetworkConnectionReconnect

Framework

app

The network connection has been restored. The “No Network” dialog is hidden. The network status icons are removed by resending the setIcons event to the Engine.

onNetworkConnectionStillDisconnected

Framework

app

Event fired when the network status is checked when the disconnected state is already set. The “No Network” dialog is displayed.

onNetworkDown

Framework

app

Event fired when the network connection is down. The “No Network” dialog is displayed.

onNetworkHideDialog

Framework

app

Event fired when the KONtx Framework detects that a network disconnected state is resolved. The default behavior is to auto-hide the “No Network” dialog box and to return to the currenlty displayed app. You can prevent the default behavior and return to the dock, or implement custom behavior in the event handler.

onNetworkRequestFailed

Framework

app

A network status request has failed. If the network is disconnected the Host event setIcons is sent and the noNetwork icon is set for the app. Otherwise the onNetworkRestored event is fired.

onNetworkRestored

Framework

app

The network restored event is fired when the network connection comes up. The “no network” dialogs are hidden. The noNetwork icon is removed from the app.

onPlayControlKeyPress

Framework

app

PLAY, PAUSE, STOP, REWIND, FORWARD keypress from the Engine. Fired after the Host event onPlaybackAction is received from the Engine or the KONtx.application manager receives the keydown event whose key codes match the KONtx.videoplayer.prototype.keys. Available in KONtx 1.2 and above.

onSelectView

Framework

app

The view has been selected.

onShowView

HostEvent, Framework

app

The app view is preparing to be made visible. The KONtx.application manager captures this Host event and refires it as a Framework event.

onUnloadProfile

HostEvent, Framework

app

The app is switching profiles. The KONtx.application manager captures this Host event and refires it as a Framework event.

onUnloadView

HostEvent, Framework

app

The app view is unloaded. The KONtx.application manager captures this Host event and refires it as a Framework event.

onUnselectView

Framework

app

The view has lost focus.

onViewChangeInitiated

Framework

app

A new view is loaded.

onWidgetKeyPress

Framework

app

KFEvent keydown keypress received from the Engine. When the keydown event is captured, the KONtx.application manager fires the Framework events onWidgetKeyPress, onPlayControlKeyPress, onColorKeyPress, or onActivateBackButton as appropriate.

Host Events Handled by KONtx.application

The following table defines the KFEvent, HostEvent and TV API events handled by KONtx.application that are not subscribeable KONtx.application events for the app developer. The KONtx.application manager subscribes to these events through the KONtx.HostEventManager interface or the widget.addEventListener() method.

Handler Name

Event Class

Received By

Description

gainfocus

KFEvent

app

The KONtx.application manager adds an event listener to the KFEvent gainfocus event by calling widget.addEventListener(). When the gainfocus event is captured, the KONtx.application manager sets the initial focus for the view and passes the Framework event onGainFocus to the view.

keydown

KFEvent

app

The KONtx.application manager adds an event listener to the KFEvent keydown event by calling widget.addEventListener(). When the keydown event is captured, the KONtx.application manager fires the Framework events onWidgetKeyPress, onPlayControlKeyPress, onColorKeyPress, or onActivateBackButton as appropriate.

onActivateAppButton

HostEvent

app

Host Event indicating that the back, home, settings, or favorite button has been activated. The KONtx.application manager captures this HostEvent and fires the Framework events onActivateBackButton, onActivateHomeButton, onActivateSettingsButton, or onActivateFavButton.

onAppFin

HostEvent

app

The app is closing down. The KONtx.application manager captures the onAppFin Host event and fires the onApplicationShutdown Framework event.

onAppInit

HostEvent

app

The app’s main file is loaded. The KONtx.application manager captures the onAppInit Host event and sets up event listeners for the app. Calls Host event listener widget.addEventListener('keydown') and fires Framework events onWidgetKeyPress, onPlayControlKeyPress, onColorKeyPress, and onActivateBackButton as appropriate. Calls Host event listener widget.addEventListener('gainfocus') and fires Framework event onGainFocus. Sends the Host event setSettings to the Engine to indicate the existence of the app’s settings page (KONtx Framework 1.2 and above). Fires the Framework events onApplicationStartup and getProfileSnippetConfs.

onGainFocus

KFEvent

app

Event passed to app’s view when the Engine sends the gainfocus event to the app.

onNetworkStatusChanged

TV API

app

The KONtx.application manager creates the tv.onNetworkStatusChanged callback function which handles the display of the network connection status icons when the network status has changed.

onPlaybackAction

HostEvent

app

Indicates a PLAY, PAUSE, STOP, REWIND, or FORWARD keypress from the Engine. The KONtx.application manager captures the onPlaybackAction Host event, sets the KONtx.videoplayer.prototype.keys key code and fires the onPlayControlKeyPress Framework event. Available in KONtx 1.2 and above.

onSelect

HostEvent

app

The button or view has been selected. The KONtx.application manager captures this Host event and fires the onSelectView Framework event.

onUnselect

HostEvent

app

The view has lost focus. The KONtx.application manager captures this Host event and fires the onUnselectView Framework event.

Child Events Sent to the Engine by KONtx.application

The following table defines the child events sent to the Engine from KONtx.application.

Handler Name

Event Class

Received By

Description

addSnippetConfs

ChildEvent

Engine

Event sent to the Engine when new bookmarks have been detected by the Framework.

deleteSnippetConfs

ChildEvent

Engine

Event sent to the Engine when bookmarks have been deleted.

exitToDock

ChildEvent

Engine

Event sent to the Engine when the app is exiting to the dock. This can occur when the app requires the network and the KONtx.application manager has detected a “no connection” state (cancel callback implemented in KONtx 1.2 and above).

setFullscreenVideoMode

ChildEvent

Engine

Event sent to the Engine to enable passthrough video to be displayed in fullscreen mode. The KONtx.application manager detects a view that must be a KONtx.system.FullscreenView with the showPassthroughVideo configuration value set to true. Available in KONtx Framework 1.2 and above.

setIcons

ChildEvent

Engine

Event sent to the Engine to set the network connection status icons (for example noNetwork).

setSettings

ChildEvent

Engine

Event sent to the Engine to indicate the existence (or lack) of the settings view so that the global toolbar settings button can be appropriately activated. Available in KONtx Framework 1.2 and above.

setSnippetConfs

ChildEvent

Engine

Event sent to the Engine to set the bookmarks for an app.

simulateFakeLoadView

Framework

app

Event sent to the KONtx.HostEventManager to invoke onShowView followed by onSelect to force a view to be loaded.

Network Disconnected State Handling

TV Apps need to detect changes in network availability and support both offline and online modes as appropriate. Testing for the "Network Disconnected" state is part of the TV App QA and approval process. To streamline getting your app into the production TV Store, be sure your app properly handles the following disconnected states:

  1. Disconnect and reconnect WAN cable from router
    • causes loss of connectivity but retains IP address
  2. Disconnect and reconnect LAN cable from router
    • causes loss of connectivity and loss of IP address
  3. Perform Use Case 1 and Use Case 2 above in the following app states:
    • Bookmark
    • Sidebar
    • Fullscreen view with TV Pass-Through off, if applicable
    • Fullscreen view with TV Pass-Through on, if applicable
    • Fullscreen view with streaming video, if applicable
Check the Network Status before calling XMLHttpRequest and URL Methods

Your app should never initiate an XMLHttpRequest or URL request when the physical network is down. You should use the KONtx.application.­­isPhysicalNetworkDown() method in tandem with the KONtx.­application.getNetworkDownStatus accessor method to differentiate between the physical network being down and a request error (from XMLHttpRequest or URL methods) set by the app.

KONtx.application.isPhysicalNetworkDown()

In KONtx Framework v1.3.18 and above the KONtx.application.­isPhysicalNetworkDown() method has been added to check if the physical network is disconnected.

  • If KONtx.application.­isPhysicalNetworkDown() returns true, the network is down and you should not make the XMLHttpRequest or URL request.
  • If KONtx.application.­isPhysicalNetworkDown() returns false, it is safe to make the XMLHttpRequest or URL request.

When the KONtx Framework detects that the physical network is down, a "Physical Disconnect" dialog is displayed.

KONtx.application.getNetworkDownStatus

The legacy accessor method KONtx.application.­getNetworkDownStatus is true when the network is disconnected or when your app's network request has failed (as set by your app).

The KONtx.application.isPhysicalNetworkDown() method only checks the status of the physical network. If this returns false, we know that the physical network is up, and it's safe to send out an XMLHttpRequest or URL request, even if the current value of KONtx.application.­getNetworkDownStatus is true. When the new request succeeds, the app should clear the request error by calling KONtx.application.­setNetworkRequestFailed(false) in the request interface.

Set the Network Status when a Network Request Fails

If your app's XMLHttpRequest or URL network request fails, the app should inform the KONtx Framework so that a “No Network” icon can be displayed on the app and a "Request Failed" dialog can be brought up. On a failed network request, the app should call KONtx.application.­setNetworkRequestFailed(true). For each successful network request, the app should set the network status to “connected” by calling KONtx.application.­setNetworkRequestFailed(false). In the example below, the method setNetworkRequestFailed() is wrapped in the myApp namespace (see the section on backward compatibility):

Handle the onNetworkHideDialog Event

The onNetworkHideDialog event allows you to have more control over what happens when network connectivity is restored. This event is fired when the KONtx Framework detects that the network issue is resolved.

The default behavior for this event is to auto-hide the "No Network" dialog box and to return to the currently displayed app. If you prevent the default behavior from happening, the dialog box will not be auto-hidden, and the consumer is forced to dismiss the dialog and returned to the dock. To change the default action, you can implement custom behavior in the event handler. To handle the onNetworkHideDialog event fired by the KONtx.application class, subscribe to it in your init.js file—for example:

If the onNetworkHideDialog event's property event.payload.type is equal to 1, the dialog about to be hidden is a "Physical Disconnect" dialog. If event.payload.type is equal to 2, the dialog is a "Request Failed" dialog.

Do not fetch data inside the onNetworkHideDialog handler as the network may be unstable. If the KONtx Framework is displaying a "Physical Disconnect" dialog, and your app has stale data or is not ready for display, you may want to call event.preventDefault(), for example:

The onNetworkConnectionReconnect event is fired when the network's physical connection is restored and stays stable for 60 seconds or more. If you subscribe to this event, subsequent network requests made by the app should succeed. However, use of this event is not recommended. The suggested best practice is to wait until the consumer accesses your app from the dock before firing new requests after a network reconnection.

Support Backward-Compatibility with other KONtx Framework Versions

To be backward-compatible with older versions of the KONtx Framework, Yahoo recommends you follow these steps:

  1. Create a custom Object to set the network down status.
  2. Use a wrapper to test for the method's existence. Define this wrapper in init.js or someplace parsed once at runtime.
  3. Set the network down status when your XMLHttpRequest or URL requests fail. On a failed network request the app should call KONtx.­application.setNetworkRequestFailed(true). For each successful network request the app should set the network status to “connected” by calling KONtx.application.­setNetworkRequestFailed(false).

Methods

void addViewConfig(Object config);

Adds a view to the app. Detects and adds any new bookmarks. The parameter config is the view’s properties.

void clearViewHistory();

Clears all view history.

void debugViewHistory();

Display the view ids of the views stored in the view history array.

void debugWhatViewsLoaded();

Display the view ids of the views that have loaded.

String getCurrentViewId();

Returns the current view Id string.

void getNetworkDownStatus();

The KONtx.application class listens to the tv.onNetworkStatusChanged event and sets the network status property. This method returns true if the network is disconnected or when your app's network request has failed (as set by your app). When the new request succeeds, the app should clear the request error by calling KONtx.application.­setNetworkRequestFailed(false) in the request interface.

Object getViewProperty(string viewId, string property);

Returns a property of a view. The view is identified by the viewId parameter. The parameter property identifies which property is returned.

void init(Object config);

Initializes the app’s views. Throws an error if properties for views, defaultViewId, and settingsViewId do not exist. Calls the addViewConfig() method for each view in the views Array. If the widgetNeedsNetwork property is not defined in the config parameter, then this property is created and set to true by default.

Boolean isPhysicalNetworkDown();

Returns true if the the physical network is disconnected and you should not make the XMLHttpRequest or URL request. Returns false if it is safe to make the XMLHttpRequest or URL request, even if the current value of KONtx.application.­getNetworkDownStatus is true. In this case, the Engine has successfully accessed the network but a local problem exists; for example, your remote servers may be down or inaccessible.

Boolean isSidebarLoaded();

Returns true if the current view does not inherit from KONtx.system.SnippetView. Useful for restricting dialogs to fullscreen and sidebar states.

void loadDefaultView();

Deletes the view history and loads the view defined by the defaultViewId property.

void loadView(string viewId, Object params, Boolean noSaveCurrentViewInHistory);

Loads an app view. If the parameter viewId is the same as the view ID returned by the getCurrentViewId() method, the "You can't switch to a view you are already on" error is thrown. If the viewId is not in the views array, the "You can't switch to a view for which we don't have a config for (typo maybe?)" error is thrown. If the viewId belongs to a bookmark view, the "You can't call loadView on a bookmark view!" error is thrown. The Object params is saved for persistent access in the next view. The next view’s this.persist property is populated with the Object params.

If the Boolean noSaveCurrentViewInHistory is false, then anything saved in the view’s this.persist property is persistently saved. When a new view is loaded, the Framework will save the current view into history. If you do not want to save a view in the history stack, you can pass a parameter true as the third parameter (pass an empty Object, {}, or null as the second parameter if you would not otherwise provide one) to loadView() to prevent the current view from being saved. This option is useful when you have a fullscreen video player and when the user hits the back button you do not want to resume playing video, but want to return to the sidebar. You should probably try and use this sparingly unless you know you really need to not store something in the history (like the video example).

The onViewChangeInitiated event is fired and the loadView event is sent to the Engine.

void loadSettingsView();

Saves the view history and loads the view defined by the settingsViewId property. If the settingsViewId is the same as the view ID returned by the getCurrentViewId() method, the "Refusing to switch to the settings view when we are already there!" error is logged.

void previousView(Object backParams);

Returns to the previous view of the app. Pops the view from the history stack and restores the previous view’s persistent data from the this.persist property. If the previous view is not on the view history stack, the view defined by defaultViewId is shown. The Object backParams is stored for future access. The onViewChangeInitiated event is fired and the loadView event is sent to the Engine. For video handling, if you are listening to both the onStopKey event as well as the onPlaylistEnd event and handling them with the KONtx.application.previousView() method, then you need to add a check around the call to KONtx.application.previousView() to make sure it only gets called once.

void reloadView(Object params, Boolean noSaveCurrentViewInHistory);

The view defined by the getCurrentViewId() method is re-loaded. The view’s this.persist property is populated with the Object params. The view’s updateView() method is called. If the Boolean noSaveCurrentViewInHistory is false, then anything saved in the view’s persist property is persistently saved. The onViewChangeInitiated event is fired and the loadView event is sent to the Engine.

void removeAllProfileSnippets();

Deletes all views that inherit from the KONtx.system.ProfileSnippetView base view. Occurs when changing profiles.

void removeView(Array ids);

Deletes an array of view ids from the app defined by the parameter ids. If only one view should be deleted, the parameter ids can be overloaded as a String containing the single view ID.

void setHostResultToViewId(Object event, String viewId, Object params);

Special case of the loadView() method that allows you to send additional information to the Engine. Set the event result to the given view config. The parameter event is an instance of KONtx.system.Event that you received in your event handler. The parameter viewId is the view ID of the view you want to be loaded. The event.HostEvent.result is set to the view config defined by the parameter viewId. The view history is cleared. The parameter params is the custom data Object you want to pass to the view upon loading.

void setNetworkRequestFailed(Boolean status);

Fires the onNetworkRequestFailed event. If the parameter status is true, sends the setIcons event with the noNetwork property. If the parameter status is false, sends the setIcons event to reset the “No Network” icon and fires the onNetworkRestored event. Hides the “Request Failed” dialog if displayed.

void setProfileSnippetViews(Array views);

Calls the Engine with the setSnippetConfs HostEvent passing in all profile-specific bookmarks found in the views parameter. The parameter views can be any app views, as only KONtx.system.ProfileSnippetViews are filtered out and passed to the Engine.

void Function.prototype.subscribeTo(Object publishingObject, StringOrArray eventTypes, Object bindingScope);

Subcribes to the event type String or Array of events defined by the parameter eventTypes that are owned by the parameter publishingObject. The optional parameter bindingScope is used to bind this function to the given scope before subscribing. This method extends the Function.prototype and is used to listen to events from any event publishing Object.

Table of Contents