Documentation Archive

Developer

Apple TV Markup Language Reference

On This Page

Compound Layout Elements

Compound layout elements are used to organize and display the elements that they contain. Each compound element organizes their contained elements differently. For example, a shelf element displays its information horizontally, while a grid element can display information horizontally and vertically.

button

A button element displays a button icon that the user can click to initiate an action. button can contain the following elements:

button can be a subelement of:

Listing 23-1 shows an example of a button element.

Listing 23-1button example TVML
  1. <button>
  2. <text>Button</text>
  3. </button>

card

The card element provides the ability to manually arrange its containing elements. The card element creates a view where the elements it contains are arranged using the tv-align and tv-position styles. Containing elements are centered by default. Figure 23-1 shows the positions inside of the card element.

Figure 23-1card element layout image: ../Art/containing_element_2x.png

Elements contained in the same position, are arranged from the top of the cell to the bottom of the cell, with regards to the order they are specified in the card element. You can specify a <background><img /></background> that displays a background image inside of the card. The background image is top-aligned and is fitted to the size of the card while keeping the image’s original aspect ratio. Text wrapping inside of the card only occurs in the header, center, and footer positions. card can contain the following elements:

card can be a subelement of:

Listing 23-2 shows an example of the card element. The text element is presented in the left position of the card element area along with a ratingBadge element.

Listing 23-2card example TVML
  1. <card>
  2. <text style="tv-position: left">Text</text>
  3. <ratingBadge value="0.8" />
  4. </card>

carousel

The carousel element displays images in a row that the user can navigate by swiping left and right on the remote. carousel can contain the following elements:

carousel can be a subelement of:

Listing 23-3 shows an example of a carousel element.

Listing 23-3carousel example TVML
  1. <carousel>
  2. <section>
  3. <lockup>
  4. <img src="" />
  5. </lockup>
  6. </section>
  7. </carousel>

collectionList

The collectionList is a container for other layout elements. collectionList can contain the following elements:

collectionList can be a subelement of:

Listing 23-4 shows an example of a collectionList element.

Listing 23-4collectionList example TVML
  1. <collectionList>
  2. <carousel>
  3. <section>
  4. <lockup>
  5. <img src="" />
  6. </lockup>
  7. </section>
  8. </carousel>
  9. <shelf>
  10. <header>
  11. <title>Shelf</title>
  12. </header>
  13. <section>
  14. <lockup>
  15. <img src="" />
  16. </lockup>
  17. </section>
  18. </shelf>
  19. </collectionList>

grid

The grid layout element displays information in a grid pattern. Items inside of the grid are displayed in a row that is bound by the size of the screen. Items are automatically moved to another row once a row is filled. grid can contain the following elements:

grid can be a subelement of:

Listing 23-5 shows an example of a grid element.

Listing 23-5grid example TVML
  1. <grid>
  2. <header>
  3. <title>Grid</title>
  4. </header>
  5. <section>
  6. <lockup>
  7. <img src="" />
  8. </lockup>
  9. </section>
  10. </grid>

imgDeck

The imgDeck contains a set of img elements. These images are part of the related content for another element. When another element, such as listItemLockup, is in focus, the information in the relatedContent element is also displayed. imgDeck can contain the following elements:

imgDeck can be a subelement of:

Listing 23-6 shows an example of an imgDeck element.

Listing 23-6imgDeck example TVML
  1. <imgDeck>
  2. <img src="" />
  3. <img src="" />
  4. </imgDeck>

infoList

The infoList element contains a set of info elements. These elements are displayed vertically, one above the the other. infoList can contain the following elements:

infoList can be a subelement of:

Listing 23-7 shows an example of an infoList element.

Listing 23-7infoList example TVML
  1. <infoList>
  2. <info>
  3. <header>
  4. <title>Director</title>
  5. </header>
  6. <text>Director Name</text>
  7. </info
  8. </infoList>

infoTable

The infoTable element displays text information in a vertical format, with each successive element directly below the previous element. infoTable can contain the following elements:

infoTable can be a subelement of:

Listing 23-8 shows an example of an infoTable element.

Listing 23-8infoTable example TVML
  1. <infoTable>
  2. <info>
  3. <header>
  4. <title>Header Title</title>
  5. </header>
  6. <text>Text</text>
  7. </info>
  8. </infoTable>

list

The list element contains nearly all other elements in the templates that use it. list can contain the following elements:

list can be a subelement of:

Listing 23-9 shows an example of a list element.

Listing 23-9list example TVML
  1. <list>
  2. <header>
  3. <title>List</title>
  4. </header>
  5. <section>
  6. <header>
  7. <title>Section 1</title>
  8. </header>
  9. <listItemLockup onselect="" />
  10. <title>Title</title>
  11. </listItemLockup>
  12. </section>
  13. <section>
  14. <header>
  15. <title>Section 2</title>
  16. </header>
  17. <listItemLockup onselect="" />
  18. <title>Title</title>
  19. </listItemLockup>
  20. </section>
  21. </list>

menuBar

The menuBar element is displayed along the top of the screen. Users can navigate left and right to move between menuBar elements. menuBar can contain the following elements:

menuBar can be a subelement of:

Listing 23-10 shows an example of a menuBar element.

Listing 23-10menuBarHeader example TVML
  1. <menuBar>
  2. <menuItem id="" >
  3. <title>Title</title>
  4. </menuItem>
  5. </menuBar>

organizer

The organizer element provides the ability to manually arrange its containing elements. The organizer element creates a view where the elements it contains are arranged using the tv-align and tv-position styles. Containing elements are centered by default. Figure 23-2 shows the positions inside of the organizer element.

Figure 23-2organizer element layout image: ../Art/containing_element_2x.png

Elements contained in the same position, are arranged from the top of the cell to the bottom of the cell, with regards to the order they are specified in the organizer element. You can specify a <background><img /></background> that displays a background image inside of the organizer. The background image is top-aligned and is fitted to the size of the organizer while keeping the image’s original aspect ratio. Text wrapping inside of the organizer only occurs in the header, center, and footer positions. organizer can contain the following elements:

organizer can be a subelement of:

Listing 23-11 shows an example of the organizer element. The text element is presented in the left position of the organizer element area and the title element is presented in the header position of the organizer element area.

Listing 23-11organizer example TVML
  1. <organizer>
  2. <text style="tv-position: left">Text</text>
  3. <title style="tv-position: header">Title</title>
  4. </organizer>

overlay

The overlay element provides the ability to place elements on top of images contained within a lockup element. The overlay element superimposes the elements it contains over the image. The overlay element creates a view where the elements it contains are arranged using the tv-align and tv-position styles. Containing elements are centered by default. Figure 23-3 shows the positions inside of the overlay element.

Figure 23-3overlay element layout image: ../Art/containing_element_2x.png

Elements contained in the same position, are arranged from the top of the cell to the bottom of the cell, with regards to the order they are specified in the overlay element. You can specify a <background><img /></background> that displays a background image inside of the overlay. The background image is top-aligned and is fitted to the size of the overlay while keeping the image’s original aspect ratio. Text wrapping inside of the overlay only occurs in the header, center, and footer positions. overlay can contain the following elements:

overlay can be a subelement of:

Listing 23-12 shows an example of an overlay element. The word Title is superimposed on top of the image pointed to in the img element.

Listing 23-12overlay example TVML
  1. <lockup>
  2. <img src="" />
  3. <overlay>
  4. <title>Title</title>
  5. </overlay>
  6. </lockup>

row

The row element provides the ability to place elements next to other elements horizontally. Elements are displayed left to right in the order they are listed inside of the row element. row can contain the following elements:

row can be a subelement of:

Listing 23-13 shows an example of a row element.

Listing 23-13row example TVML
  1. <row>
  2. <buttonLockup>
  3. <badge src=""/>
  4. <title>Title 1</title>
  5. </buttonLockup>
  6. <buttonLockup>
  7. <badge src=""/>
  8. <title>Title 2</title>
  9. </buttonLockup>
  10. </row>

section

The section element groups elements together so they can be treated as a single element for layout purposes. section can contain the following elements:

section can be a subelement of:

Listing 23-14 shows an example of a section element.

Listing 23-14section example TVML
  1. <section>
  2. <lockup>
  3. <img src="" />
  4. <title>Title 1</title>
  5. </lockup>
  6. <lockup>
  7. <img src="" />
  8. <title>Title 2</title>
  9. </lockup>
  10. </section>

segmentBar

The segmentBar element contains a list of segmentBarItem elements that are displayed horizontally. Users can use the controller to move the cursor between the contained segmentBarItem elements. segmentBar can contain the following elements:

segmentBarcan be a subelement of:

Listing 23-15 shows an example of a segmentBar element.

Listing 23-15segmentBar example TVML
  1. <segmentBar>
  2. <segmentBarItem itemCount="12">
  3. <title>Today</title>
  4. </segmentBarItem>
  5. <segmentBarItem itemCount="9">
  6. <title>This Week</title>
  7. </segmentBarItem>
  8. </segmentBar>

separator

The separator element creates a visible, horizontal line to separate areas on a page. separator can contain the following elements:

separator can be a subelement of:

Listing 23-16 shows an example of a separator element.

Listing 23-16separator example TVML
  1. <separator>
  2. <button>
  3. <title>Title</title>
  4. </button>
  5. </separator>

stack

The stack element groups elements together and lays them out vertically, starting from the top of the containing element. Each element is placed directly underneath the preceding element. stack can contain the following elements:

stack can be a subelement of:

Listing 23-17 shows an example of a stack element.

Listing 23-17stack example TVML
  1. <stack>
  2. <title>Title</title>
  3. <row>
  4. <buttonLockup>
  5. <badge src=""/>
  6. <title>Title 1</title>
  7. </buttonLockup>
  8. <buttonLockup>
  9. <badge src=""/>
  10. <title>Title 2</title>
  11. </buttonLockup>
  12. </row>
  13. <description>Description</description>
  14. <text>Text</text>
  15. <row>
  16. <buttonLockup>
  17. <badge src=""/>
  18. <title>Title 3</title>
  19. </buttonLockup>
  20. <buttonLockup>
  21. <badge src=""/>
  22. <title>Title 4</title>
  23. </buttonLockup>
  24. </row>
  25. </stack>

tumblerBar

The tumblerBar element contains a list of tumblerItem elements that are displayed horizontally. Users can use the controller to move between the contained tumblerItem elements. tumblerBar can contain the following elements:

tumblerBar can be a subelement of:

Listing 23-18 shows an example of a tumblerBar element.

Listing 23-18tumblerBar example TVML
  1. <tumblerBar>
  2. <tumblerItem>
  3. <title>Title</title>
  4. <subtitle>Subtitle</subtitle>
  5. </tumblerItem>
  6. <tumblerItem>
  7. <title>Title<2/title>
  8. <subtitle>Subtitle2</subtitle>
  9. </tumblerItem>
  10. </tumblerBar>