Review the Sample TV App Files

There is no limit to the number of files that make up a single app. TV Apps can have many images and text objects, multiple JavaScript sections (often in external files), and can create new objects at runtime to implement complex functionality. The examples in this section show a simple app, described in only a few files, to present a structured approach for creating more complex apps.

Setup the TV App File Structure

The examples in this section are based on the MediaPlayerSample app which can be used as a starting point to build your own video app. Your app files should be organized in a folder structure that looks like this:

In the production environment, each app is stored in a top level app directory. Within this directory, each individual app (for example, MediaPlayerSample) is stored in a zipped package whose file extension is .widget, for example, MediaPlayerSample.widget. When you submit your app to the TV Store this .widget directory should be zipped using the following naming convention:


For example:


Make sure you zip your app from the .widget directory (and not from the Contents directory).

It is important that the zipped package that contains your app has .widget file extension, and that it contains a directory called Contents in which your main.TV file should be placed. The very first file that the Engine loads is the XML file named main.TV. In a very simple app main.TV can include the app’s application code, however for most apps, main.TV is used to load the external JavaScript files through the <script> tag. Please check that the file extension .TV for main.TV is capitalized or the app will not load.

You can put any other files or directories anywhere within your Contents folder, but we recommend organizing them into Images, Javascript, and Resources directories. Certain OEMs require that you store the app icon in the Contents/Images/960x540 directory so it can be re-used to represent your app in other contexts, see the section Create an Icon for the TV Store. External JavaScript files can be stored in a Javascript folder. Typically the first JavaScript file loaded is the basic initialization of a app named init.js.

Establish the TV App File Paths

File paths in the Engine are always relative to the location of the main.TV file which is found in the Contents directory. This means a file reference without a directory, for example init.js, is looked for in the same directory as the main.TV file, while a file reference with a directory, for example Javascript/init.js, is looked for in the specified subdirectory, in this example the Javascript subdirectory. Do not use absolute paths, which are paths that begin with a forward slash character (/).

Review the Yahoo Connected TV KONtx Framework

All the examples provided in this section are built using the Yahoo Connected TV KONtx Framework,  a flexible application generator which supports the creation of all types of TV Apps. The KONtx Framework encapsulates all communication with the Engine and provides pre-packaged user interface components and building blocks for app developers. The KONtx Framework combines basic elements, controls, and themes to provide ready-to-use user interface components. The call stack for KONtx Framework development is illustrated below:

You can review the KONtx Framework JavaScript source code located at $HOME/YCTV-ADK/YCTV-SIM-XXX/data/Overlay/Script/Framework/ after the ADK is installed and the latest production apps are updated. You can review the KONtx API Reference at

Define the TV App Main Program

The main.TV file is the starting point of the app (the main program) and is the first file executed by the Engine. This file typically contains the <script> tag to include external JavaScript files for the app. The .TV file extension for the main.TV file must be capitalized or the app will not load.

At this point in the tutorial, you should have already extracted the MediaPlayerSample app to your local development environment, see the section Extract a Sample TV App to your Development Directory. To view an example of the main.TV file, open the /devapps/MediaPlayerSample.widget/Contents/main.TV file in the text editor of your choice.

File main.TV:

The main.TV file starts with the XML <widget> tag. This tells that Engine that the app code is starting. You will also notice that at the very end of the main.TV file, there is a </widget> end tag, which tells the Engine that it has reached the end of the code for the app.

After the <widget> tag, the first line of your app’s XML should be a <script> tag to include the local initialization file. This file initializes the app with the KONtx Framework and includes all of the JavaScript code for the app. The Javascript directory is found in the app’s Contents directory, for example you can find the init.js file at this location:


Define the TV App Metadata

A separate file that encapsulates all the app’s metadata is called widget.xml. This file should be placed in the same directory as your main.TV file. The widget.xml file includes information such as the app’s name, unique identifier, author, description, and security information. All your app metadata can be placed in the widget.xml file. You must have a minVersion attribute set to 5.0 to take advantage of the latest Engine.

Along with your app's metadata, the widget.xml file also specifies security settings for your app. The security element controls access to resources such as the filesystem, http, command, and more. Open the /devapps/MediaPlayerSample.widget/Contents/widget.xml file in the text editor of your choice.

File widget.xml:

These are examples of the common tags that you will find within the widget.xml file:

  • <metadata> — Starts the app metadata.
  • <name> — Defines the app’s name.
  • <version> — Defines the version of the app.
  • <identifier> — Defines a unique identifier for the app.
  • <author> — Defines the app’s author, organization, and support URL.
  • <copyright> — Identifies the copyright information.
  • <description> — Provides a description for the app.
  • <platform minVersion="5.0"> — Defines the required version of the Engine.
  • <security> — Defines the filesystem, system command, and http security for the app. Required to be defined exactly as shown above.
  • <image usage="960x540.logo" src="Images/960x540/logo.png"/> — Defines the standard screen logo for the top of the sidebar.
  • <image usage="960x540.icon" src="Images/960x540/icon.png"/> — Defines the standard screen icon for the TV Store. This icon is used by various OEMs to represent the app. A 44x44 pixel image is required to be included in the Contents/Images/960x540/ directory.

Define a Unique TV App Identifier

The widget.xml file includes an <identifier> field which defines the app’s unique identifier. You can use any value for this identifier as long as it is guaranteed to always be unique. No two apps should have the same value for app identifier.

When uploading your app to the TV Store, the upload API will check for uniqueness and return an error if you try to submit an identifier that violates the uniqueness rule. To be safe, we recommend using a reverse domain name. A reverse domain name provides structure for organizing multiple apps.

Using a reverse domain name for a app identifier adds a line to widget.xml that looks like this:


Using a unique identifier allows the Engine to identify your app, even if you change the name or other metadata.

Update the TV App Version

The widget.xml file includes a <version> field to define the app’s version. A valid version value is three integers separated by periods: major number, minor number, and micro number, for example:


The TV Store uses the app version to determine if a new release should be auto-downloaded to the consumer’s device. It is the responsibility of the app developer to increment the version for each release.

Create Logo and Icon Images

An image dictionary is used to store and access images for each app based on a usage key. The image dictionary is first populated via <image> tags in the widget.xml file when the app is first installed. For each <image> tag in the widget.xml file you can declare images for specific usages with the usage attribute.

Two images are typically defined in the widget.xml file, for example:

<image usage="960x540.logo" src="Images/960x540/logo.png"/>
<image usage="960x540.icon" src="Images/960x540/icon.png"/>

Each image in the dictionary has a predetermined usage string that the dock uses to lookup images when required. Usage strings can be of these types: logo, loading, placeholder, or icon.

  • The logo image is used to store the logo image at the top of the sidebar.
  • The loading image is used as a transitional image while the dock is loading.
  • The placeholder image is used for view-specific and profile-specific bookmark images.
  • The icon image is used for the TV Store, the "About" page and in OEM-specific contexts. A 44x44 pixel image is required to be included in the Contents/Images/960x540/ directory.

Each usage string is scoped first by the connected TV device resolution: 960x540.

Initialize the TV App Views

In this example, the first file loaded by the Engine main.TV includes the init.js file to initialize the user interface views that the app displays. These views include bookmark views, sidebar views, and fullscreen views. These components of the TV App user interface are described below.

Bookmark Views

The dock is a containing application from which apps are launched on the TV. The dock is displayed at the bottom of the screen when the Yahoo TV Key is pressed on the remote control.

Bookmark views are the horizontal tiles within the dock which provide dynamic content and a shortcut to launch the individual app. The following example shows the basic structure of the dock. Four bookmark (formerly called snippet) tiles are shown in the dock. The first bookmark has focus. Focus is fixed in the leftmost position and bookmarks slide under this focal area when the LEFT and RIGHT ARROW keys are pressed on the remote control.

Sidebar Views

Sidebar views provide navigation within a single app. The sidebar is the primary view of a app. All implementations of apps must display a sidebar. The following example shows the basic structure of a app sidebar.

Fullscreen Views

Fullscreen views provide a graphical display that takes up the whole screen. It is the largest view of an app. When playing fullscreen video, no app user interface components are displayed on the screen and the entire screen is covered by streaming video. You can launch the fullscreen view from the dock or from a sidebar view, however the app’s main bookmark should not launch into fullscreen mode. Transport controls (play, pause, stop and others) can be displayed on top of fullscreen video. The following example shows the app playing fullscreen streaming video.

The following example shows transport controls (play, pause, stop, and others) overlaid on the fullscreen streaming video.

Initialize the KONtx Framework Application Manager

The KONtx Framework's JavaScript is included in the first line of the init.js file. The KONtx Framework defines the elements, components, controls, and behaviors of the KONtx objects used for the rapid development of apps.

The following is a sample of a very simple init.js file.

File init.js:

The Media Player Sample app is implemented using the KONtx Framework defined in Framework/kontx/version/src/all.js, replacing the version variable with the latest KONtx Framework version. You can review the KONtx Framework JavaScript source code located at $HOME/YCTV-ADK/YCTV-SIM-XXX/data/Overlay/Script/Framework/. You can review the KONtx API Reference at

After the KONtx Framework is included, the next three lines of init.js include the app’s JavaScript. In these files the various view classes are extended for the app’s functionality. These files are reviewed below.

The next line in the init.js file initializes the KONtx application manager to track the views and normalize communication with the Engine. This is implemented by calling the KONtx.application.init(Object config) method passing in a config object. The config parameter includes a views array in which each view is defined by a view ID, a view class, and an optional data parameter. The config parameter also defines two special view IDs, the default view ID and the settings view ID. The view identified by the defaultViewId property is the navigation start point or HOME of your app. The view identified by the settingsViewId property is displayed when the GREEN key on the remote control is pressed. The settingsViewId is typically used for the “About Page” of the app, and can be set to the default view KONtx.views.AboutBox.

In the config object the views and defaultViewId properties are required. The settingsViewId property is recommended. The widgetNeedsNetwork property is optional. If your app does not require a network connection set the widgetNeedsNetwork property to false. If the widgetNeedsNetwork property is not defined in the config parameter, then this property is created and set to true by default.

TV App JavaScript code is structured around views and view classes. In the Media Player Sample app there are four views initialized by the KONtx application manager:

File init.js:

  • The view-Main view is a simple sidebar view implemented by the SampleSidebarView class in the Javascript/views/sidebar.js file. This view launches the fullscreen streaming video. This view is launched by the snippet-main view.
  • The view-Player view is a simple fullscreen view implemented by the BasicPlayerView class in the Javascript/views/basicplayer.js file. This view plays streaming video and supports the transport controls for the video. This view is launched by the view-Main view.
  • The view-Settings view is the default sidebar view for the “About Page” functionality defined in the KONtx.views.AboutBox class. This view is used to display app metadata and is launched by the GREEN key on the remote control.
  • The snippet-main view is the bookmark view for the app. It is implemented by the SampleSnippetView class in the Javascript/views/snippet.js file. The bookmark view is displayed in the dock and launches the view-Main sidebar view.
View Base Classes

Each view initialzed by the application manager extends the KONtx Framework view base classes. The basic app views (bookmark, sidebar, and fullscreen) are represented by these KONtx Framework classes:

  • The KONtx.system.SnippetView class is an abstract base class for bookmarks, use AnchorSnippetView and ProfileSnippetView to create bookmark views.
  • The KONtx.system.AnchorSnippetView class is the main bookmark view for the app which is not removed when switching profiles if both profiles have the app installed.
  • The KONtx.system.ProfileSnippetView class is a profile specific bookmark view which is removed when switching profiles.
  • The KONtx.system.SidebarView class is a sidebar view.
  • The KONtx.system.FullscreenView class is a fullscreen view.

View class events and methods are simplified to support the concepts of UI component creation and content update. To create a view for your app, you extend the view class and override two app-specific methods: createView(), and updateView(). The method createView() is where you create the basic user interface components in the view. No content is present at this stage. The createView() method is called once. The method updateView() is where you populate the view with content. The updateView() method is called each time a user views the page, or the data on the page has been updated. The user interface components in the view do not need to be physically re-rendered to update data in the view.

Using the methods createView() and updateView() allows the Engine to optimize rendering views. Once createView() is called, the Engine does not need to create the XML elements onscreen again. Calling the updateView() method is fast because it can swap content inside the view without having to re-render the XML, which is often slow.

View Conventions

Auto-resuming is the process by which a view is hidden and then shown again, through the back button or other means. When the view was hidden, garbage collection may have occurred. To present a consistent context to the user for this view, the app developer may want the view to auto-resume with the same data, focus, and state that was previously shown. For a control to be recognized for auto-resuming inside each view you must save the controls you create in the this.controls structure.

The following structures are commonly used in views:

  • this.config – Properties passed into the view at instantiation.
  • this.persist – Persistent storage for anything you want to persist when this view gets reloaded after possible garbage collection
  • this.cache – Structure for transient data.
  • this.controls – References to view controls.

Create a Bookmark View Class

As an app author, you can control what is displayed in your bookmark. You can supply an image for a static bookmark or more dynamic graphics to show vitality through automatic updates–for example, a stock ticker.

In each bookmark you can specify text and graphics to be displayed. For example, if you were writing an email app, you might display the number of unread mail messages in the email bookmark. A weather app might display the current temperature and other weather data in its bookmark.

The following is example JavaScript for the bookmark view for the MediaPlayerSample app.

File Javascript/views/snippet.js:

The SampleSnippetView class extends the KONtx.system.AnchorSnippetView class. For optimization purposes, this bookmark view is not removed when switching profiles if both profiles have this app installed. When this bookmark is selected, the sidebar view defined by the defaultViewId, in this example view ID view-Main, is launched.

The createView() method is overloaded to create a KONtx.element.Text object whose label is the localizable string 'media_player_snippet'. The styles object defines simple text styles (white, large, centered) for the bookmark text. The text object is stored in the this.controls object for auto-resuming purposes.

Create a Sidebar View Class

Create the main sidebar view for the app and define the menu navigation for the HOME page. The HOME page represents the starting point of your app. It is the first sidebar view launched by your main bookmark view and is identified by the defaultViewId in init.js, in this example represented by view ID view-Main.

For each sidebar view, you can define the buttons, the images, the text, and the title bar. You can specify any number of sidebar views to display in your app. Each sidebar represents a single page of content which you can control. The content in the sidebar is inset between the title menu at the top of the page and the global navigation buttons at the bottom of the page. The following is JavaScript for the main sidebar view for the MediaPlayerSample app.

File Javascript/views/sidebar.js:

The SampleSidebarView defined above is a view class that extends the KONtx.system.SidebarView. The SampleSidebarView class overrides the createView() method. The createView() method is called when the onLoadView and onCreateView events are triggered by the Engine. The createView() method renders the view.

In this example, createView() creates two KONtx.control.TextButton buttons which when selected load the view-Player fullscreen view defined in Javascript/views/basicplayer.js.

Each button's onSelect event handler calls the KONtx.application.loadView() method. The KONtx.application.loadView(string viewId, Object params, Boolean noSaveCurrentViewInHistory) method loads an app view defined by the first parameter viewId, in this example view-Player. The second parameter Object params is saved for persistent access in the next view using the this.persist view property. If the parameter Boolean noSaveCurrentViewInHistory is false (or undefined), then anything saved in the view’s this.persist property is persistently saved in a history stack. In this example the PlaylistID is stored persistently and passed to the view-Player view when the button is selected.

After all the buttons are defined, the sidebar’s remaining space is filled with the KONtx.control.EmptySpace object, which provides a professional looking background.

Create a Fullscreen View Class

The fullscreen view is the largest graphical view of an app. You can launch the fullscreen view from the dock or from a sidebar view. You cannot use an app’s main bookmark to launch a fullscreen view, but you can use another bookmark. In the general case, the entire screen resolution is covered by the app’s graphical interface or by streaming video. To create a multimedia effect, the app may take over only a portion of the fullscreen resolution–for example, the bottom third of the screen, and leave video or television running in the background. This state may not be supported by all OEMs.

In fullscreen mode, there are no reserved buttons or regions. The title button and the global toolbar are not present. A wait indicator may be displayed if the Engine or a remote server is performing a time-consuming function. When implementing the fullscreen view, the GREEN, YELLOW, and BLUE color-coded remote control keys are available for app control. It is recommended that the BLUE key on the remote control be used to resize the video where applicable.

From the fullscreen view you can exit to the dock or you can exit to fullscreen video. When you exit from the fullscreen view to fullscreen video, all graphics on the screen are cleared, and the app gives up user interface control to the device’s media player. At this point, the device’s media transport controls are available.

The following is example JavaScript for the fullscreen view for the MediaPlayerSample app.

File Javascript/views/basicplayer.js:

The BasicPlayerView class defined above extends the KONtx.system.FullscreenView to play streaming video using the entire screen. The first method overridden in this view is the initView() method which initializes the KONtx.mediaplayer and instantiates dialog boxes for error handling. The next method, createView(), is called once when the view is first rendered. This method creates the media transport controls (play, pause, stop and others) using the KONtx.control.MediaTransportOverlay object and appends it to the view.

The media player listens and responds to the following events: onStateChange, onPlaylistEnd, and onStreamLoadError. If the media has stopped playing, the fullscreen view is hidden and the user is returned to the sidebar view, SampleSidebarView.

File Javascript/views/basicplayer.js:

If an error state is detected by the media player a dialog box is displayed using the KONtx.dialogs.Alert class. The error dialog has a Retry Again button that calls the method KONtx.mediaplayer.playlist.start() to restart the playlist and a Cancel button that takes the user back to the previous sidebar view, SampleSidebarView.

File Javascript/views/basicplayer.js:

The SamplePlayerView class overrides the focusView() method to overlay the transport controls on top of the streaming video.

File Javascript/views/basicplayer.js:

The updateView() method is overriden to start media playback. The this.persist.PlaylistID object was passed from the SampleSidebarView view from the KONtx.application.loadView('view-Player', { PlaylistID: 1 }); call. In the _startPlaylist() method called by updateView(), the newest playlist is created as a object and the network bandwidth is set using the KONtx.mediaplayer.setConnectionBandwidth() method. Finally the media playback is started by the KONtx.mediaplayer.playlist.start() method.

File Javascript/views/basicplayer.js:

Table of Contents