Tvdml NPM | npm.io

TVDML

New!

This is the new version of tvdml, 6.X.

Update highlights

Switched TVML renderer to React.js (Breaking).
Unified different ways to create TVML documents (Breaking).
Simpler syntax to create stylesheets using <style> element (Breaking).
Improved Menu button detection.
Changed TVDML.renderModal() rerendering behavior (Breaking).

Migration guide

Check out migration guide from 5.X.

For the older version of tvdml, refer to the 5.X branch.

Intro

This is a library that's the main goal is to greatly simplify app development for Apple TV using React.js and provide tools to solve problems like:

React.js integration with TVML and TVJS.
Routing.
Event binding.
"Menu" button detection.

System Requirements

Starting from 4.X TVDML drops support for tvOS < 10. If you need that support please consider using 3.X.

Getting started

TVDML is shipping as npm package and can be installed with npm or yarn. In addition you'll need to install React.js.

npm install --save tvdml react

Or using yarn

yarn add tvdml react

TVDML is written in ES6 and built using UMD wrapper so it can be used in any environment with any of this ways:

// Directly from global scope.
App.onLaunch = function() {
  console.log(TVDML);
}

// Or with CommonJS if you are using bundlers like browserify.
var TVDML = require('tvdml');

// Or with ES6 imports.
import * as TVDML from 'tvdml';

// You can use ES6 destructuring if you need only few
// of the provided features.
import { subscribe, handleRoute, navigate } from 'tvdml';

// Or even require modules from their sources.
import { handleRoute, navigate } from 'tvdml/src/navigation';

Requiring modules from their sources can help you decrease app size if you are using rollup for your builds.

Despite being written totally in ES6 TVDML is not forcing you to use it.

But you should agree that this...

App.onLaunch = function(options) {
  evaluateScripts([
    options.BASEURL + 'libs/tvdml.js',
    options.BASEURL + 'libs/react.js',
  ], function(success) {
    if (success) {
      TVDML
        .render(function(payload) {
          return React.createElement(
            'document',
            null,
            React.createElement(
              'alertTemplate',
              null,
              React.createElement(
                'title',
                null,
                'Hello world'
              )
            )
          );
        })
        .sink();
    }
  });
}

Doesn't look as nice as this

import React from 'react';
import * as TVDML from 'tvdml';

TVDML
  .subscribe(TVDML.event.LAUNCH)
  .pipe(TVDML.render(payload => (
    <document>
      <alertTemplate>
        <title>Hello world</title>
      </alertTemplate>
    </document>
  )));

So what we need to be able to write code as in second example? Well it's not that simple but this tvdml-boilerplate repo will shed the light on basic build configuration.

Well! Now we know how to write apps using ES6 and JSX so let's start from the basic features!

Routing

tvOS provided great foundation to write apps using TVML and TVJS. But you need somehow to react on user's activity and map it to the UI.

To help you solve this issues TVDML provides navigation module.

import React from 'react';
import * as TVDML from 'tvdml';

TVDML
  .subscribe(TVDML.event.LAUNCH)
  .pipe(() => TVDML.navigate('start'));

TVDML
  .handleRoute('start')
  .pipe(TVDML.render(() => (
    <document>
      <alertTemplate>
        <title>This is initial view</title>
        <description>You can now navigate to another view</description>
        <button onSelect={event => TVDML.navigate('next')}>
          <text>Go to next page</text>
        </button>
      </alertTemplate>
    </document>
  )));

TVDML
  .handleRoute('next')
  .pipe(TVDML.render(() => (
    <document>
      <alertTemplate>
        <title>This is next view</title>
        <description>Now you know how to use routes!</description>
      </alertTemplate>
    </document>
  )));

This is a small example of navigation and rendering modules usage which helps handle routes and show views to the user.

Here is a complete navigation module api:

TVDML.handleRoute(routeName) — Creates pipeline for route handling. Only one pipeline can be created for the route. Otherwise it will throw error.
TVDML.dismissRoute(routeName) — Destroy previously created route pipeline. Can destroy only created pipelines. Otherwise it will throw error.
TVDML.navigate(routeName[, params][, isRedirect]) — Navigation trigger. Will invoke registered route pipeline with passed params if they are specified. Route pipeline will result in creating new navigation document. if param isRedirect is passed then route pipeline will replace current navigation document with new one.
TVDML.redirect(routeName[, params]) — Same as TVDML.navigate(routeName, params, true).

import * as TVDML from 'tvdml';

TVDML
  .subscribe(TVDML.event.LAUNCH)
  .pipe(() => TVDML.navigate('start', { foo: 'bar' }));

// To create route handler use `handleRoute` method.
TVDML
  .handleRoute('start')
  .pipe(payload => {
    const {
      route,
      redirect,
      navigation,
    } = payload;

    console.log(route); // 'start'
    console.log(redirect); // false
    console.log(navigation); // { foo: 'bar' }
  });

// `dismissRoute` method will help you destroy route handler.
TVDML.dismissRoute('start');

Here is a list of predefined constants for system events:

TVDML.event.EXIT
TVDML.event.ERROR
TVDML.event.LAUNCH
TVDML.event.RELOAD
TVDML.event.RESUME
TVDML.event.SUSPEND

This events are related to system handlers: App.onLaunch, App.onExit etc.

Why would you use this events and not system handlers directly? Handlers can be assigned only once and events can be attached multiple times. But no one force you to use them.

You can add event listeners like this:

import * as TVDML from 'tvdml';

TVDML
  .subscribe(TVDML.event.LAUNCH)
  .pipe(eventSymbol => console.log('App is launched!'));

const suspendEventPipeline = TVDML
  .subscribe(TVDML.event.SUSPEND)
  .pipe(eventSymbol => console.log('App is sent to background'));

// To destroy event pipeline use `unsubscribe` method.
suspendEventPipeline.unsubscribe();

To know more about how pipelines works check Pipelines section.

Also there are some predefined routes that may help you:

TVDML.route.NOT_FOUND — Will be invoked when navigation module was unable to find match to requested route.

The next big thing is...

Using React.js

With TVDML your main way to create documents will be React.js.

Here is a list of all available documents in TVML.

To render any react component you need to provide rendering factory to TVDML.render pipeline.

Pipeline's payload will be passed as the first argument to rendering factory so you'll be able to map it's props to rendering tree.

import React from 'react';
import * as TVDML from 'tvdml';

TVDML
  .subscribe(TVDML.event.LAUNCH)
  .pipe(TVDML.render(payload => (
    <document>
      <alertTemplate>
        <title>Hello world</title>
      </alertTemplate>
    </document>
  )));

Here is how to render any component you like:

import React from 'react';
import PropTypes from 'prop-types';
import * as TVDML from 'tvdml';

function Hello(props) {
  return (
    <document>
      <alertTemplate>
        <title>Hello {props.name}</title>
      </alertTemplate>
    </document>
  );
}

Hello.propTypes = {
  name: PropTypes.string,
};

Hello.defaultProps = {
  name: 'world',
};

TVDML
  .subscribe(TVDML.event.LAUNCH)
  .pipe(TVDML.render(payload => (
    <Hello name="user" />
  )));

It's just plain old React.js.

But there are some things you need to remember about TVML and React.js.

Because TVML and TVJS are not your normal browser they have some limitations. And to be able to work with them as best as possible react's tvml renderer have some quirks:

Attribute names should be written in props as they are written in docs. There is no className to set class attribute.
Events are normal DOM events provided by TVML.

Everythin else should be as you expected.

Rendering to player's documents

player.overlayDocument and player.interactiveOverlayDocument are not default targets for rendering components but there are two ways to do this:

Sink empty document to TVDML.render():

const document = TVDML.createEmptyDocument();

const pipeline = TVDML.render(() => (
  <document>
    <alertTemplate>
      <title>Hello</title>
    </alertTemplate>
  </document>
));

pipeline.sink({ document }).then(() => {
  player.interactiveOverlayDocument = document;
});

Use TVML renderer directly

const document = TVDML.createEmptyDocument();

TVDML.ReactTVML.render((
  <document>
    <alertTemplate>
      <title>Hello</title>
    </alertTemplate>
  </document>
), document, () => {
  player.interactiveOverlayDocument = document;
});

Just don't forget to unmount components when you clear player's documents or you may face memory leaks and many other issues.

You can unmount component by passing previously rendered document to TVDML.ReactTVML.unmountComponentAtNode(document).

Modals

Modals are perfect when you need to show some useful information but don't want to interupt opened view context. You can use TVDML.renderModal() method to render any document you want in overlay. TVDML.renderModal() behaviour is similar to TVDML.render().

There is also TVDML.removeModal() method that removes any presented modal document. Or TVDML.dismissModal() to compose modal dismissal with other operations.

import React from 'react';
import * as TVDML from 'tvdml';

TVDML
  .subscribe(TVDML.event.LAUNCH)
  .pipe(() => TVDML.navigate('start'));

TVDML
  .handleRoute('start')
  .pipe(downloadTVShows())
  .pipe(TVDML.render(payload => (
    <document>
      <stackTemplate>
        <banner>
          <title>TV Shows</title>
        </banner>
        <collectionList>
          <grid>
            {payload.tvshows.map(tvshow => {
              return (
                <lockup onSelect={showTVShowDescription.bind(this, tvshow)}>
                  <img src={tvshow.cover} width="250" height="250" />
                  <title>{tvshow.title}</title>
                </lockup>
              );
            })}
          </grid>
        </collectionList>
      </stackTemplate>
    </document>
  )));

function showTVShowDescription(tvshow) {
  // Creating modal document rendering pipeline.
  const pipeline = TVDML.renderModal(() => (
    <document>
      <descriptiveAlertTemplate>
        <title>{tvshow.title}</title>
        <description>{tvshow.description}</description>
      </descriptiveAlertTemplate>
    </document>
  ));

  // Invoking created pipeline.
  pipeline.sink();
}

Every next invocation of TVDML.renderModal() will rerender active modal without closing it.

If you need to close and then open modal again use TVDML.dismissModal() pipeline.

TVDML
  .subscribe(TVDML.event.LAUNCH)
  .pipe(TVDML.renderModal(() => (
    <document>
      <descriptiveAlertTemplate>
        <title>Modal #1</title>
      </descriptiveAlertTemplate>
    </document>
  )))
  .pipe(TVDML.dismissModal())
  .pipe(TVDML.renderModal(() => (
    <document>
      <descriptiveAlertTemplate>
        <title>Modal #2</title>
      </descriptiveAlertTemplate>
    </document>
  )));

Working with `menuBar`

One of the trickiest things in TVML is configure and use menu bar across multiple views.

TVDML provides easy to use solution for this issue.

import React from 'react';
import * as TVDML from 'tvdml';

TVDML
  .subscribe(TVDML.event.LAUNCH)
  .pipe(TVDML.render(() => (
    <document>
      <menuBarTemplate>
        <menuBar>
          <menuItem route="search">
            <title>Search</title>
          </menuItem>
          <menuItem route="my" autoHighlight>
            <title>My</title>
          </menuItem>
          <menuItem route="all">
            <title>TV Shows</title>
          </menuItem>
          <menuItem route="settings">
            <title>Settings</title>
          </menuItem>
        </menuBar>
      </menuBarTemplate>
    </document>
  )));

TVDML
  .handleRoute('my')
  .pipe(...);

TVDML
  .handleRoute('all')
  .pipe(...);

TVDML
  .handleRoute('search')
  .pipe(...);

TVDML
  .handleRoute('settings')
  .pipe(...);

Views switching will be handled by TVDML. All you have to do is to create menuItem elements with defined route attribute which must point to defined routes.

If you want to select specific menu item use autoHighlight attribute for this purpose.

Styling elements

There are two ways to style elements:

Using style prop to write inline styles. style prop is key-value dictionary. Keys are style names written in camelCase.
Using <style> element to define stylesheets + class prop to bind them to elements.

import React from 'react';
import * as TVDML from 'tvdml';

TVDML
  .subscribe(TVDML.event.LAUNCH)
  .pipe(TVDML.render(payload => (
    <document>
      <head>
        <style>{`
          .title {
            tv-text-style: title1;
          }
        `}</style>
      </head>
      <alertTemplate>
        <title class="title">Hello user</title>
        <description style={{ tvTextStyle: 'title2' }}>
          Nice to see you
        </description>
      </alertTemplate>
    </document>
  )));

All available styles can be found here: TVML Styles.

Events

Here is everything as in React.js except that all events are native TVML events.

List of controllable elements:

button
lockup
listItemLockup

List of available handlers:

onPlay — Triggers when "Play" button is pressed.
onSelect — Triggers when Touchpad is pressed.
onChange — Triggers when element change its value. <ratingBadge /> for example.
onHighlight — Triggers when element becoming highlighted.
onHoldselect — Triggers when Touchpad is pressed with a long press.
onNeedsmore — Triggers when user approaches end of the list by scrolling.

<button onSelect={event => console.log(event.target)}>
  <text>Press Me</text>
</button>

Working with `DataItem`

In tvOS 11 DataItem binding api was presented to fix performance issues with large documents that may ended up with very long parsing and rendering.

Here is a short example how Apple suggests to use it.

So now you may wondering how we can use this cool feature in JSX?

We got you covered! Here is an updated example from "Requesting and rendering data" section:

const tvshows = [
  {
    title: 'Arrow, Season 1',
    url: 'http://is2.mzstatic.com/image/thumb/Music6/v4/e9/bb/9b/e9bb9bbb-16c0-d946-063d-15632dd78a76/source/600x600bb.jpg',
  },
  {
    title: 'Arrow, Season 2',
    url: 'http://is1.mzstatic.com/image/thumb/Music3/v4/bb/87/84/bb8784ca-7e31-0cc1-b56d-9243624863d3/source/600x600bb.jpg',
  },
  {
    title: 'Arrow, Season 3',
    url: 'http://is2.mzstatic.com/image/thumb/Video62/v4/ec/ca/78/ecca78a3-5bb0-0b32-954c-f7fd966582ab/source/600x600bb.jpg',
  },
];

TVDML
  .handleRoute('start')
  .pipe(TVDML.render(() => (
    <document>
      <stackTemplate>
        <banner>
          <title>TV Shows</title>
        </banner>
        <collectionList>
          <shelf>
            <prototypes>
              <lockup prototype="tvshow">
                <img
                  binding="@src:{url};"
                  width="300"
                  height="300"
                />
                <title binding="textContent:{title};" />
              </lockup>
            </prototypes>
            <section
              binding="items:{tvshows};"
              onSelect={event => console.log(event.target.dataItem)}
              dataItem={{
                tvshows: mockData.map((cover, i) => {
                  const item = new DataItem('tvshow', i);

                  item.url = cover.url;
                  item.title = cover.title;

                  return item;
                }),
              }}
            />
          </shelf>
        </collectionList>
      </stackTemplate>
    </document>
  )));

The key difference from the example provided by Apple is dataItem attribute. It's responsible to apply DataItems to final document and this:

<section
  binding="items:{tvshows}"
  dataItem={{
    tvshows: tvshows.map(tvshow => {
      const item = new DataItem('tvshow', i);

      item.url = cover.url;
      item.title = cover.title;

      return item;
    }),
  }}
/>

Is same as:

<section binding="items:{tvshows}" />

function parseJson(information) {
  const results = JSON.parse(information);

  const parsedTemplate = templateDocument();

  navigationDocument.pushDocument(parsedTemplate);

  const shelf = parsedTemplate.getElementsByTagName('shelf').item(0);
  const section = shelf.getElementsByTagName('section').item(0);

  section.dataItem = new DataItem();

  const newItems = results.map((result) => {
      const objectItem = new DataItem(result.type, result.ID);
      objectItem.cover = result.cover;
      objectItem.title = result.title;
      return objectItem;
  });

  section.dataItem.setPropertyPath('tvshows', newItems);
}

Complete rendering api

TVDML.render(renderFactory) — Main rendering pipeline for React.js components. Responsible for rendering new document to navigationDocument or update previously rendered documents passed through pipeline.
TVDML.renderModal(renderFactory) — Same as TVDML.render() but for modals.
TVDML.dismissModal() — Pipeline that removes active modal with ability to track progress.
TVDML.removeModal() — Utility over TVDML.dismissModal(). Use it when you don't need to track modal dismissal and don't want to invoke pipeline manually.
TVDML.ReactTVML — Publicly exposed React.js' reconciler for TVML. May be useful for advanced usage. It contains next methods:
- render(element, container, callback) — Mount React.js element to container (usualy TVML document).
- unmountComponentAtNode(container) — Unmount active React.js components at container and clears markup.
TVDML.createEmptyDocument() — Method to create empty TVML document. May be useful when using TVDML.ReactTVML directly. It does same as:
```
DOMImplementationRegistry.getDOMImplementation().createDocument();
```

Pipelines and Streams

To be able to easily manage your data flows TVDML provides two additional utils. They are Streams and Pipelines. They have similar api but a little different behaviours. All core functionality in TVDML is based upon them.

Streams

Streams can be created using TVDML.createStream() factory and can be described as event bus with ability to combine transforms and create forks. Here is an example:

const head = TVDML.createStream();

head.pipe(value => console.log(value));
head.pipe(value => console.log(value));

head.sink(1);

Console:

1
1

This code will be resulted with two records in the console because we create two forks of the main stream and all of them will receive sinked value.

Every pipe creates another stream that can be used separately:

const head = TVDML.createStream();
const tail = head.pipe(value => log(value + 1));

tail.pipe(value => log(value * 3));

head.sink(1);
tail.sink(1);

function log(value) {
  console.log(value);
  return value;
}

Console:

2 // ┬── 1 + 1
3 // │ ─── 1 * 3
6 // └── 2 * 3

As you can see 2 and 6 were produced by sinking 1 to head stream and 3 were produced by sinking 1 to tail stream. 3 is placed between 2 and 6 because of using promises to resolve pipes.

Promises execution scheduled after current event loop.

Streams can be combined:

const head1 = TVDML.createStream();
const head2 = TVDML.createStream();

head1
  .pipe(value => log(value + 1))
  .pipe(head2)
  .pipe(value => log(value + 2))

head2
  .pipe(value => log(value + 3))
  .pipe(value => log(value + 4))

head1.sink(1);

function log(value) {
  console.log(value);
  return value;
}

Console:

2 // ┬─┬ 1 + 1
5 // │ ├── 2 + 3
9 // │ └── 5 + 4
4 // └── 2 + 2

Pipe transformations supports promised operations:

const head = TVDML.createPipeline();

head
  .pipe(value => {
    return new Promise(resolve => {
      setTimeout(() => resolve(log(value + 1)), 100);
    });
  })
  .pipe(value => log(value + 2))
  .sink(1);

function log(value) {
  console.log(value);
  return value;
}

Console:

2 // (100ms)
4

Streams' public api

pipe(handler) — Fork parent stream and apply transform provided by handler function. handler can be function or other stream.
sink(value) — Emit passed value to stream and all of its forks. Returns promise that will be resolved when all branches will process sinked value.

Pipelines

Pipelines are streams too. But instead sinking values from the starting point of the stream you create processing pipeline with transformations and sink values from its end. Only requested brunch will be executed. Other forks stays untouched.

Let's compare with streams' first example:

const head = TVDML.createPipeline();

head.pipe(value => console.log(value));
head
  .pipe(value => console.log(value))
  .sink(1);

Console:

As we can see only sinked branch were exected.

Let's compare other examples:

const head = TVDML.createPipeline();
const tail = head.pipe(value => log(value + 1));

tail.sink(1);
tail
  .pipe(value => log(value * 3))
  .sink(1);

function log(value) {
  console.log(value);
  return value;
}

Console:

2 // ─── 1 + 1
2 // ┬── 1 + 1
6 // └── 2 * 3

Combining pipelines:

const head1 = TVDML.createPipeline();
const head2 = TVDML.createPipeline();

const tail2 = head2
  .pipe(value => log(value + 3))
  .pipe(value => log(value + 4));

head1
  .pipe(value => log(value + 1))
  .pipe(tail2)
  .pipe(value => log(value + 2))
  .sink(1);

function log(value) {
  console.log(value);
  return value;
}

Console:

2  // ┬── 1 + 1
5  // ├── 2 + 3
9  // ├── 5 + 4
11 // └── 9 + 2

Pipelines' public api

pipe(handler) — Fork parent pipeline and create new one with applying transform provided by handler function. handler can be function or other stream or pipeline.
sink(value) — Emit passed value to pipeline from its first pipe. Returns promise that will be resolved when all transforms in pipeline will process sinked value.

Rules of combining streams and pipelines

If stream is passed as handler it will pass incoming value to next pipe without changes.
If pipeline is passed as handler it will return computed value to next pipe.

Additional tools

Detecting Menu button press

tvOS and TVJS aren't providing any way to detect Menu button activity on Apple TV Remote (Siri Remote). To be able to detect when user returns from active screen to previous TVDML provides special event that describes activitiy that is posible only with press of the Menu button.

TVDML
  .subscribe('menu-button-press')
  .pipe(transition => {
    console.log(transition); // { from: { route, document, modal }, to: { route, document, modal } }
  });

With this snippet you can detect when user returned to specific screen and perform some activity like update results etc.

function isMenuButtonPressNavigatedTo(targetDocument) {
  return ({ to: { document } }) => targetDocument === document;
}

class MyComponent extends React.PureComponent {
  componentDidMount() {
    const currentDocument = this.document.ownerDocument;

    this.menuButtonPressStream = TVDML.subscribe('menu-button-press');
    this.menuButtonPressStream
      .pipe(isMenuButtonPressNavigatedTo(currentDocument))
      .pipe(isNavigated => isNavigated && this.loadData().then(this.setState.bind(this)));
  }

  componentWillUnmount() {
    this.menuButtonPressStream.unsubscribe();
  }

  loadData() {...}

  render() {
    return (
      <document ref={node => (this.document = node)}>
        ...
      </document>
    );
  }
}

TVDML
  .createPipeline()
  .pipe(TVDML.render(() => (
    <MyComponent />
  )));