Documentation Archive


Apple TV Markup Language Reference

On This Page


Use the list template (listTemplate) to display a list of items; for example, a list of the user’s favorite movies. Whereas you use the catalog template to display categories of a product (action movies, comedies, favorite movies), you use the list template to display actual contents of one category, such as a list of the user’s favorite movies. The items are listed on the right side of the screen with like items grouped together in a section. A title providing a brief description of the items is contained in a header area directly above the listed items. When an item is selected, information about the item is displayed on the left side of the screen. Figure 8-1 shows the basic layout for a listTemplate page. The theme for the list template defaults to the system preference.

Figure 8-1List template image: ../Art/ATV_temps_list_2x.png

Main Elements of the List Template

Listing 8-1 shows the main elements in TVML format, and Table 8-1 describes the main elements.

Listing 8-1listTemplate TVML format
  1. <listTemplate>
  2. <banner>
  3. </banner>
  4. <list>
  5. <header>
  6. </header>
  7. <section>
  8. <listItemLockup>
  9. <title>…</title>
  10. <relatedContent>
  11. </relatedContent>
  12. </listItemLockup
  13. </section>
  14. </list>
  15. </listTemplate>

Table 8-1listTemplate element descriptions

Element name



Element containing background information and the page title.


Information describing what a section contains.


Element containing all content for the listTemplate page.


Element containing all information that pertains to one list item, such as an item title and image, as well as related content.


Information that is displayed on the left side of the screen when an item in the list is highlighted.


An area of the page that groups related elements together as one element, for layout purposes. In this case, the section contains list items.

List Template Example

Listing 8-2 shows the TVML for a listTemplate example. Figure 8-2 shows the output for the example. An image and a description that relate to the highlighted item are displayed on the left side of the screen.

Listing 8-2listTemplate example TVML
  1. <document>
  2. <listTemplate>
  3. <banner>
  4. <title>Johnny Appleseed's Movie Collection</title>
  5. </banner>
  6. <list>
  7. <header>
  8. <title>Favorite Movies</title>
  9. </header>
  10. <section>
  11. <listItemLockup>
  12. <title>Movie 1</title>
  13. <relatedContent>
  14. <lockup>
  15. <img src="path to images on your server/Car_Movie_1920x1080.png" width="857" height="482" />
  16. <title>Movie 1</title>
  17. <description>A brief description for the first movie should go here.</description>
  18. </lockup>
  19. </relatedContent>
  20. </listItemLockup>
  21. <listItemLockup>
  22. <title>Movie 2</title>
  23. <relatedContent>
  24. <lockup>
  25. <img src="path to images on your server/Car_Movie_800x600.png" width="857" height="482" />
  26. <title>Movie 2</title>
  27. <description>A brief description for the second movie should go here.</description>
  28. </lockup>
  29. </relatedContent>
  30. </listItemLockup>
  31. <listItemLockup>
  32. <title>Movie 3</title>
  33. <relatedContent>
  34. <lockup>
  35. <img src="path to images on your server/Car_Movie_720x720.png" width="857" height="482" />
  36. <title>Movie 3</title>
  37. <description>A brief description for the third movie should go here.</description>
  38. </lockup>
  39. </relatedContent>
  40. </listItemLockup>
  41. </section>
  42. </list>
  43. </listTemplate>
  44. </document>
Figure 8-2listTemplate example output image: ../Art/listTemplateSS_2x.png