Documentation Archive


TVML Programming Guide

On This Page

Creating Your First TVML App

When you create your first TVML app, you set up a server and create the initial TVMLKit JS file.

Setting Up Your Server

Users access content through an app on Apple TV. However, the app usually does not store all of the information on the Apple TV. Instead, the app acts as a gateway and shows the user what information is available and retrieves the information when the user requests it. If the app stored all of the available options on the Apple TV, any time new content was added the user would be required to update and download the app, whether they wanted to view the new content or not. Store information on a server to avoid unnecessary downloading.

You need to decide whether to host your content on your own server or through a hosting site. Use a hosting site to remove the need to set up and run your own server. Any server outages are taken care of by the hosting site. However, if any problems arise, you have to wait for the hosting site to fix the problem instead of trying to take care of the problem yourself.

Host your own server to provide greater control over how your content is organized and its up time. You are also responsible for ensuring that your server is always running or else users will not be able to access your content. For information on setting up your own OS X server, see Install OS X Server and Configure Xcode Server.

Whether you decide to use a hosting site or to host your own server, you need to know the path to your initial TVMLKit JS file. From there, you can access your TVML page templates.

Creating the Xcode App

When a user turns on their Apple TV, a list of apps appears on their main page. These apps are created using Xcode. TV template apps created in Xcode are simple apps that point to the initial TVMLKit JS file for the app and are created like any other Xcode project. When creating a new template app, select tvOS -> Application -> TVML Application as shown in Figure 2-1.

Figure 2-1Creating an Apple TV template app image: ../Art/XcodeTVMLTemplate_2x.png

After you enter a name for your product, a skeletal app is created. Inside of the AppDelegate.swift file, two static constants have been created: tvBaseURL and tvBootURL. tvBaseURL contains the URL that points to your server. tvBootURL contains the location of your initial TVMLKit JS file. The TVML Application template sets tvBaseURL to a local server and tvBootURL to a TVMLKit JS file named application.js. You need to change these variables to point to your server and your initial TVMLKit JS file. A standard web server is required to host your assets, which you can host yourself, or you can leverage one of numerous cloud hosting providers. Either way, you need to know the path to your initial TVMLKit JS file. From there, you can access your TVML page templates.

Putting It All Together

After you set up the server information and create the Xcode app, the final step is to create the initial TVMLKit JS file. At its most basic, your initial TVMLKit JS file must implement the App.onLaunch function. Inside of this function, the following actions are required to display a page:

  • A variable containing valid TVML code.

  • Parsing the TVML code into a Document Object Model (DOM) tree.

  • Pushing the parsed DOM tree onto the navigation stack.

Figure 2-2 shows how the navigation stack grows and shrinks as documents are pushed onto and popped off of the navigation stack.

Figure 2-2TVML navigation stack

To display your first page, create a new file named HelloWorld.js and place the code listed in Listing 2-1 inside the file. In your Xcode app, change the tvBootURL constant to “\(AppDelegate.tvBaseURL)/HelloWorld.js”. Start a server and run your app. For testing purposes, you can create a local server using the python -m SimpleHTTPServer 9001 command from the Terminal app. Ensure you run the local server from the same directory as your TVMLKit JS file.

Listing 2-1 shows the code required to display a spinner with the words “Hello World!” on the television screen. The template variable contains the TVML code required to create a loading template screen. A new DOM parser is created and the TVML code is sent to the parser. The resulting DOM tree is saved in the parsedTemplate variable. Finally, the parsed DOM tree is pushed onto the navigation stack and displayed on the television screen. Figure 2-3 shows the Apple TV output using the HelloWorld.js listing.

Listing 2-1HelloWorld.js listing
  1. App.onLaunch = function(options) {
  2. var template = '<document><loadingTemplate><activityIndicator><text>Hello World!</text></activityIndicator></loadingTemplate></document>';
  3. var templateParser = new DOMParser();
  4. var parsedTemplate = templateParser.parseFromString(template, "application/xml");
  5. navigationDocument.pushDocument(parsedTemplate);
  6. }
Figure 2-3HelloWorld.js output image: ../Art/HelloWorld_js_ss_2x.png

Listing 2-1 is a very basic example of how to create a TVML page. Most real world apps are much more complex. However, as will be shown in the next chapter, being able to directly create a TVML page in your TVMLKit JS file and display it has several real world applications.