TV Apps Layouts


This documentation covers TV apps built using Quick Brick SDK 5.x.x or later. The major differences to previous TV releases are;

  • TV apps now follow mobile Quick Brick apps based on a Theme > Group > Component > Cell app layout structure.
  • Hard coded screen layout values are replaced by fully configurable component plugins allowing flexible component positioning within a screen.
  • A single, highly flexible power cell replaces the two previous limited power cells.
  • Cells can now have any image size and aspect ratio.
  • Group components are supported as on mobile.
  • Headers are now independent components operating in the same way as mobile.
  • Fixed styling of the screen picker is now replaced by a fully style-able screen picker component.

The Zapp tools used and the process of building and releasing apps for TV platforms is the same as for mobile apps however, there are some platform specific considerations to take into account.

  • A TV layout will be different to mobile.
  • A single layout is possible across all supported TV devices.
  • Datasources can be common to both mobile and TV apps but images used in a TV layout will have different resolutions to mobile. Image keys for TV layouts should be included in data sources.
  • TV app navigation is built around a remote control and driven by the 5-point Nav method of Up, Down, Left, Right, OK (Enter), Back (Return) and Exit.
  • TV apps tend to have a much flatter layout structure, avoiding the deep nesting of screens that need to be navigated back out of.
  • TV apps only contain live, linear or VOD content. Content types such as Articles and Web Links used in mobile apps cannot be used.
  • TV apps can only have a single cell in focus at any time. It is not possible to have focusable action buttons within a cell. However, it is possible to create the appearance of buttons in an app using the TV power cell, they just happen to be individual cells themselves.

TV Layout Creation

In your app family select the Studio button

In the pop up box select Add New Layout

When creating a new layout for TV apps in Zapp Studio configure the following

  • Give the layout a name
  • Set the target to be TV
  • Select if you are using Pipes v2 for this layout
  • Set Cell Style Framework to Cell Style Builder

Screen types

TV apps currently have one screen type - the General Component Screen. In Zapp Studio select Add Screen and then select General Content for each screen that you need in the app.

Component Types

The following component types can be added to the General Content Screen

  • Horizontal List
  • Grid
  • Group
  • Group Info
  • Screen Picker

Horizontal List

The Horizontal List distributes content across a linear horizontal, scrollable and focusable rail.

Click Add Component in a general content screen and select the Horizontal List (Quick Brick) component.

The Horizontal List needs to be attached to

  • A data feed to populate its content
  • A power cell for its specific styling

Each Horizontal list in a screen is configured in Zapp Studio as follows

  • The Item Limit within the component. Set to between 1 (e.g .for a single banner type cell) or leave unset to be unrestricted and display all items in a data feed.
  • Cell Selectable yes / no: If set to NO then the component is focusable but no items can be selected. This could be used in future programs in an EPG for instance, where there is no action associated with selecting a future program.
  • Clear Cache On Reload always checks for updates to the data source feed when the component reloads.
  • Enable Data Refresh If this is set to ON then the rail will automatically refresh its content at the time interval set (in seconds). Use this in live linear and event based content data feeds to indicate via a badge that an item has changed state e.g. from ‘coming soon’ to ‘on now’
  • Attach the component to its data source
  • Select an optional target screen that will launch when an item in the component is selected. e.g. to go to a further show or episode screen
  • Component Anchor Point defines the Y position that any individual component will scroll and anchor to as the screen components are navigated. Typically each component in a screen has the same anchor value but they could be different.
  • Component Margin Top and Bottom defines the gap at the top and bottom of the screen to components. (Default from Theme Plugin is 60px to avoid overscan cropping of content on TV screens)
  • Component Padding Left and Right sets an internal gap within the component at its left and right ends. Use this to set the gap to the screen edges for the first and last items in the list (Default from Theme Plugin is 90px to avoid overscan cropping of content on TV screens)
  • Component Padding Top and Bottom sets blank padding space inside each component at its top and bottom.
  • Component Gutter Horizontal sets the gap between cells in the Horizontal List
  • Component Background Color can be used to define a color behind all cells on the component.
  • Cell Width in pixels defines the width of all cells in the component. The height of a the cell is then calculated automatically from the width, aspect ratio of the image in a cell, the amount of text displayed and any included line height and padding values.
  • Cell Styles - Attach a power cell style to your components
  • Show Header - leave set to off, do not use (see group components for adding a header to a component)

Examples of Horizontal Lists Styled Using Power Cell 1 TV

Grid Component

A Grid Component distributes content in a scrollable and focusable x-y grid presentation. Click Add Component in a general content screen and select the Grid (Quick Brick) component

Many of the Grid configuration parameters are the same as for Horizontal List. Additional Grid specific configuration items are;

  • Component Gutter Vertical the gap between cell rows in the grid
  • Number of columns set this to how many columns you require in a grid and the grid will automatically scale to fit the screen with that number of columns.

5 Column Grid Example

Group Component

Groups are used to

  • Automatically distribute content in a single feed across a repeated pattern of components
  • Include a Component Title, also known as Group Info or Component Header.

Any number of Grids and Horizontal Lists can be contained within a single Group Component.

Any number of groups can be put into a screen.

Data feeds are added at group level, not to the individual components within them. The feed is then distributed across the group.

To add a group to a screen select Add Component and select the Group Component (Quick Brick)

Then select the Group Component itself in your screen before adding individual Horizontal Lists and / or Grids with in it.

When in a group all components must have a fixed number of items defined in their Item Limit setting otherwise the group will not display correctly and the content will just fill the first unlimited component.

A Group can be configured to

  • No Repeat Content will distribute across the components in a group until it runs out of components to populate
  • Repeat All Components All components in the group will repeat until there is no content left in the feed
  • Repeat Last N Components Define which components you want to repeat. Useful for not repeating the header before each repeated pattern, or repeating just the horizontal rails under a large show banner.

Adding Headers (Titles) to Groups

To display a title (header) with a Horizontal List or Grid component create a group and add the Group Info Quick Brick component as the first component in the Group.

Use the Group Info Component styling parameters to control margins and paddings and hence the header position on the screen.

Attach the Group Info Component to a specific instance of the Group Info Cell TV power cell and style the cell accordingly.

The information displayed in a header such as title is taken from the feed. Use the data-key field in the Group Info Cell to determine what data is displayed.

Any number of Group Info Components can be added to a group e.g. to display a title, then a summary.

Power Cells for TV

TV apps currently support 2 power cell types

  • Cell 1 TV
  • Group Info Cell

Cell 1 TV

Individual instances of Cell 1 TV are added to each H List and Grid Component per style required.

Cell 1 is highly flexible and can be used to create cells that have

Image only

Text only

Image & Text with the text displayed below the image or overlaying the image (use negative margins on text fields to push up and overlay the image)

  • Any size (using pixel width parameter for H List and number of columns parameter for Grid)
  • Any aspect ratio - select other in the power cell aspect ratio field and type in the desired aspect ratio in the format 16x9, 1x1, 2x3 etc.
  • Add rounding to images and cells

  • Define focus states. Choose from
  • Text color
  • Text background color
  • Image or cell border
  • Image or cell top or bottom highlight line
  • Cell background color

Add positionable badges per content type or static badges. These can be used to show that an item has changed its state from ‘coming soon’ to ‘on now’, or that the item is free or needs ot be paid for. Note that TV apps do not support content of type = ‘article’ or ‘link’ compared to mobile apps.

Add a positionable runtime label sourcing its data from the duration data in a feed

3 style-able text labels that can present title, summary or connect to any desired metadata key in the component’s feed. Per TV platform Font Type Font Size Font Spacing Line Height Font Color No of Lines

  • Do not use the Action Button Field in a TV app. This is used for favourites and share in mobile apps and is not supported on TV apps.

Group Info

Use this within a group component with a grid or horizontal list to display headers (titles)

In TV apps Group Cell Info

  • Can only contain text
  • Cannot have action buttons or badges
  • Are not focusable or selectable (unlike mobile apps which can use them to link to ‘more’ content directly from the header).
  • Text can be styled per TV platform for font type size weight color spacing etc.

TV Top Menu

The Top Menu must be used in an app and contains the following components;

  • A single option left image for logos (only one logo can be used)
  • Screen Navigation Buttons
  • A single optional Right Action Button e.g. for a settings page.

The following restrictions apply to the Top Menu.

  • Only 1 TV Top Menu can be used in an app
  • Only 8 items max can be added to the top menu
  • Very large font sizes and long strings will result in the menu being truncated. Keep menu titles short and font sizes reasonable.

To add the Top Menu to an app in Zapp Studio

Click on the Navigation view tab

Click on the Add Navigation button

Select the TV Top Menu Bar

To add an item to the Top Menu Bar

  • Click on the Top Menu Bar in the left panel of Zapp Studio

  • Click on Add Item

  • Select an item from the 3 options of Left image, Screen Navigation Button, or Right Action Button

Style The Menu item

Left image is added as an image upload and must be .png at 300px x 60px. Transparent alpha can be used around a logo to make it fit the required 300px x 60px frame.

Screen Items for navigation buttons only support text at present.

  • Set Data Target to the screen for that Navigation Button and edit the title. (By default the menu will set the title to be the name of the screen selected though this can be over-ridden)
  • Set Screen Presentation to default
  • Set Button State to Text. Do not use Image.

Right Action Button

  • Select Image for the Button State
  • Upload 3 x png images at 48px x 48px with transparent alpha for the 3 button states.
  • Set the target screen to launch when selecting this menu item

Screen picker

The Screen Picker is a side menu that can be added to a screen to present e.g. sub categories of that screen. More than one screen picker can be used in an app, attached to their own specific main menu screen. Very flexible screen picker styling can be made.

To create a screen picker add a new screen to a layout of type = General Content and name it e.g. Screen Picker 1

In this screen select New Component and add the Screen Picker Quick Brick TV component


Once one screen picker is added to a screen no other component type may be added to this screen.

Attach a feed to the screen picker. A Screen Picker may be driven from a Data Source Feed or a Manual Feed to create the list of screens in the picker.

Content in a screen picker may optionally be connected to a further target screen that will launch a new screen presentation when a content item in the first screen picker is selected. This can be used to build nested screen picker structures for further sub-categories.

The screen picker can be styled with respect to

  • Position on the screen relative to the top and left of the screen (x and y co-ordinates)

  • The gap (gutter) between screen picker items

The width of the seen picker

  • The font type font weight font size letter spacing line height, per TV platform
  • The maximum number of lines of text (wrapping) to present in all entries
  • The focus state method to use i.e text color cell background color text background color text underline or text border border and background rounding
  • 4 focus states exist to differentiate between by styling the screen picker; selected, unselected, in focus and unselected, in focus and selected

The default values for the screen picker style are as below

Using a Manual Feed for a Screen picker

In Zapp Studio create as many new screens as required to cover the number in your screen picker list.


Screen Pickers should usually use a Grid Component. Horizontal Lists can also be used but never use a Carousel Component. Attach each component to a feed for their content

Create a Manual Feed, listing as many entries as you require in the screen picker. The title you give to each item is what will appear in the screen picker. Attach each item to a screen created in the previous step.

Add this manual feed to the main screen picker feed source.