Best practices – rails

Instead of using one template for all content, break the content down into one template per screen.

This reduces the size of the response object, making your app much faster.

The Content Delivery service supports paged content – that is, delivering only part of the required data at a time. It supports horizontal paging; that is, within a rail, you can retrieve just enough items to fill the visible space, rather than all the items in the rail.

See:

1. Refer to Retrieve all or part of the rails and related content for a template to get all the rails in a template.

2. Then refer to Retrieve a specific rail and its contents to get the specific rails you want, with their contents. Use the limit, offset, and page parameters to get only the number of content items that you need.

It is a good idea to retrieve more content than you need to display initially. That way, when the user scrolls, the newly-displayed part of the screen is already populated and they do not need to wait for items to load.

A good starting point is to retrieve twice as many items as the screen can display, in each direction, which means:

• Get twice as many rails as the screen can display vertically.

• Within each rail, get twice as many items as the screen can display horizontally.

You can use the multiplier that works best for you to manage the trade-off between UI performance and response object size.

Different devices will typically have different scrolling speeds. For example, a user on a mobile device can scroll faster than a one using a TV remote to scroll.

So you may find that a different multiplier is appropriate for each type of device.

See the links in Use the paging functionality, above.

Example

If you have decided that you want to get twice as much content than can be displayed, both vertically and horizontally, then you would need to do something like this for the template that corresponds to the screen you are displaying:

1. Make a GET request to Content Delivery's templatesummary endpoint to get all the rails for the template's current layout:

   CODE

   https://server:port/contentdelivery/v1/templatesummary/{templateid/templatename}

2. Let's say there is space in the viewport for five rails (vertically). So you want to get ten rails. For each of the first ten rails listed in the response from the above call, you would make a GET request to Content Delivery's rails endpoint:

   CODE

   https://server:port/contentdelivery/v1/templateviews/{templateid/templatename}/rails/{railId}?limit=10&page=1

   Use the limit and page parameters to get the required number of horizontal items in each rail:

   • limit – the number of items per page

   • page – the page for which to return items (starts at 1)

3. When the user scrolls a rail horizontally, make additional GET calls to the rails endpoint to retrieve more items:

   CODE

   https://server:port/contentdelivery/v1/templateviews/{templateid/templatename}/rails/{railId}?limit=10&page=2

   CODE

   https://server:port/contentdelivery/v1/templateviews/{templateid/templatename}/rails/{railId}?limit=10&page=3

   ... and so on.

4. When the user scrolls vertically, repeat step 2 to retrieve more rails.

Typically different teams will be responsible for template creation and client app integration. It is important for both teams to:

• Understand these best practices.

• Know what each other are doing.

This approach allows the client integrators to know which template they should be using for each screen. It is up to you how you manage this, but suggested options include:

• Using an agreed naming convention for templates, layout, and rails.

• Using remote configuration to enable the client app to know which templates to use.

Remote configuration is outside the scope of the Content Delivery service. However, it does have an endpoint that allows the client to retrieve all the available templates.

See Retrieve all templates with child template IDs.

You have to name your templates, layouts, and rails. Deciding on a sensible naming convention for each will help avoid confusion.

You are recommended to name the first template default or home.

It may be that you will need to make changes to template metadata that break backwards-compatibility (for example, changing the key name for a key/value pair that is already in use).

In this case, creating a new version of an existing template is encouraged.

Once all clients have been upgraded to the new version, you can retire the older template.

This approach incurs an overhead – any changes (e.g., scheduling new versions) must be made to all such templates.

See Creating, editing, and deleting templates.

Custom metadata (key/value pairs) can be added at three levels:

• To templates

• To rails

• To sections within rails

• To individual content items

Which level you add them at depends on what you are trying to achieve.

For example, you could:

• Add a key/value pair to a rail to indicate to the client app that it should style that rail differently from other rails.
  (Similarly, you could do the same for sections or individual content items to present them differently within their rail.)
  

• Add key/value pairs to a custom section that the client app could use to insert an item to represent a third-party application.
  You might have separate key/value pairs to specify:

  • The title of the app

  • The app's bundle ID

  • The URI of the image to be used for the app within the rail
    Note:

    Only use this approach in situations where images are not available from OpenTV Video Platform.

    For regular content items, you are recommended to get images from the ImageService.

    See Use ImageService to get images.

See:

• Creating, editing, and deleting templates

• Creating, editing and deleting rails

• Adding content to a rail

You can use multiple layouts to create a layout that only applies for a specific time period (for example, for Christmas or other important seasonal event).

This allows you to make planned changes in advance without having to edit the current (live) layout.

Never make changes to a current (live) layout. Use multiple layouts and switch the active (default) layout as required instead.

See Scheduling layouts [DEPRECATED].

Templates can be arranged in a hierarchy of parent, child, and sibling templates.

Arrange your templates in the same hierarchy as the screens in your application. For example, if your app has a Home screen that allows users to access a Sports screen and a Kids screen, make your Sport and Kids templates children of your Home template.

Alternatively, your application can dynamically generate its screen hierarchy based on the template hierarchy.

When your application calls Content Delivery to get the templates, the template objects in the response are organised in the hierarchy in the same way as they are organised in Rails Builder.

See:

• Retrieve all templates with child template IDs

• Retrieve all templates with all their child templates

• Creating, editing, and deleting templates

Adding too many rails to a page or adding too much content to an individual rail can lead to a situation where users will give up on scrolling and not reach content that you would like them to see.

Recommendations:

• If you want to add many rails, put them on separate pages/templates instead of all on one page/template.

• Use the looping scroll interface paradigm (where the UI starts at the first rail again when the user reaches the bottom and starts from the beginning of the rail if the user reaches the end of the rail).

It is possible to add individual items to a rail. But it is not very flexible.

Adding items to a content group allows you to reuse the group of items in multiple rails.

You can:

• Create a dynamic content group, which contains content that match the specified criteria (in OpCon).

• Create a content group that contains the content that you specify (through API calls).