Display and navigate between TVML documents on Apple TV by retrieving and parsing information from a remote server.
- tvOS 12.1+
- Xcode 11.3+
- TVMLKit JS
Configure the Sample Code Project
Before running the app, you need to set up a local server on your machine:
In Finder, navigate to the CreateTVMLApp directory inside of the CreateTVMLApp project directory.
In Terminal, enter at the prompt,
cdfollowed by a space.
Drag the CreateTVMLApp folder from the Finder window into the Terminal window, and press Return. This changes the directory to that folder.
In Terminal, enter
ruby -run -ehttpd . -p9001to run the server.
Build and run the app.
After testing the sample app in Apple TV Simulator, you can close the local server by pressing Control-C in Terminal. Closing the Terminal window also kills the server.
Display the Initial Document
application file controls the app. The app creates two global variables that contain URL information. When the app launches, the app populates the variables with information contained in the
App file and retrieves the first document from the server.
Retrieve a TVML Document From the Server
While you can’t control a user’s internet access, you can control what they see on the screen. To avoid showing a blank screen, create and display a loading document to provide users with a visual cue that your app is working, despite not having a connection to the server.
Create a new
XMLHttp to retrieve information from the server. After successfully loading a new document, push the document onto the navigation stack to display it.
Replace the Previous Document
After the user selects a new document, push that document onto the navigation stack. This places the new document at the top of the current document stack and displays it. When the user presses the Menu button on the Siri Remote, the system removes the current document from the stack and displays the previous document. Doing this causes the previous loading document to display when you want the user to see the selection document.
To fix this, replace the loading document with the new document using the
replace method. The following function takes the new document and the loading document as parameters and replaces the loading document with the new document.
Select a New TVML Document
Each file on your server contains the information to display a single document onscreen. In this app, the initial document contains information that displays two images, each with their own title. Each image is a Lockup Elements element. When the user selects a lockup, the app uses the
onselect attribute to call the
get method. The lockup passes the URL for the next document to the
The image element contains the URL and size specifications for the displayed image.
<img width="182" height="274" src="http://localhost: