<!-- Title: atvjs - Apple TV application development framework Description: Blazing fast Apple TV application development using pure JavaScript. Author: Emad Alam --> <meta name="keywords" content="tvos, tvml, tvjs, tvml framework, apple tv framework, tvjs framework, apple tv javascript development">

atvjs

Blazing fast Apple TV application development using pure JavaScript.

<!-- MarkdownTOC depth=4 autolink=true autoanchor=true bracket=round -->

• Philosophy
• What's included
• Getting Started
• Basic Examples
  • Creating Pages
  • Adding TVML styles to your page
  • Fetching data from a remote source
  • Creating links to other pages
• Advanced Topics
  • Event Handling
  • Custom options while navigation
  • Creating Menu Page
  • Application initialization using configuration
• Sample Code
• Useful Links
• Contributions
• License

<!-- /MarkdownTOC -->

<a name="philosophy"></a>

Philosophy

What?

This is a super simple framework for blazing fast Apple TV application development using pure JavaScript. It relies on the tvOS provided TVML and TVJS for Apple TV development. However this framework does most of the heavy lifting for you and lets you concentrate on your application logic without worrying about the hassles of complicated architecture for Apple TV development. Build your Apple TV application the same way how you are used to building your SPA applications in JavaScript and let the framework handle the rest for you.

Why?

The existing application architecture and sample code provided by apple for building the Apple TV applications using TVML and TVJS appears to be very immature (no offense Apple) and feels more like the web applications of the 90s where each of the page loads separately by sending the request to the back-end which generates your application page markup based on the user interaction and sends the new page back to the browser. This is okay if we were still in the 90s but feels so dumb in this era where we are used to building SPAs with REST APIs and back-end is used just as a data interaction point. Here comes atvjs that bridges the gap and lets you use the same architecture that, we as front-end developers, have embraced over the years.

How?

You simply create your pages (views) by passing a bunch of configurations (name of the page, template function, url etc) with your desired data (you can either populate data manually using your own ajax requests or pass a url configuration to fetch data from your server). Once the page is created, it is uniquely identifiable using the name. You can navigate to your page anytime in your application using the same name.

<a name="whats-included"></a>

What's included

• Page, Menu and Modal Creation and Navigation ATV.Page.create, ATV.Menu.create, ATV.Navigation.navigate, ATV.Navigation.navigateToMenuPage, ATV.Navigation.presentModal
• TVML styling capabilities (both global as well as individual page level)
• Event handling (both global and for individual pages and elements)
• Application level persistent data storage using localStorage with lz-string compression ATV.Settings.set, ATV.Settings.get, ATV.Settings.remove
• Ajax library using JavaScript Promises ATV.Ajax, ATV.Ajax.get, ATV.Ajax.post, ATV.Ajax.put, ATV.Ajax.del
• Application level publish/subscribe using PubSubJS ATV.subscribe, ATV.publish, ATV.unsubscribe
• Application initialization/reload using simple configurations ATV.start, ATV.reload
• Global error handling
• JavaScript Promise and other ES6 Features Polyfill using babel
• lodash library as ATV._

<a name="getting-started"></a>

Getting Started

atvjs is defined as a UMD and available as an npm package. You can either import it as a dependency or download it independently and include in your project.

$ npm install --save atvjs

You'll then be able to use it as a dependency with your favorite module system.

import ATV from 'atvjs';
// or
var ATV = require('atvjs');

Or if you have downloaded a copy of atvjs, pull the script inside your application after launch.

function onEvaluate(success) {
	if (!success) {
		// application failed to load
	}
}

App.onLaunch = function(options) {
	var baseurl = options.BASEURL;
	App.launchOptions = options;
	evaluateScripts([`${baseurl}atv.min.js`, `${baseurl}app.js`], onEvaluate);
};

// then in your app.js you will have the instance of ATV library available
// you can contain your entire application code inside app.js

<a name="basic-examples"></a>

Basic Examples

<a name="creating-pages"></a>

Creating Pages

Create pages in your application using the page factory. You will then be able to navigate to these pages using the name of the page.

ATV.Page.create({
	name: 'home',
	// use a template function from your favourite templating engine
	// or pass a raw template function
	template(data) {
		return `<document>
					<alertTemplate>
						<title>${data.title}</title>
						<description>${data.description}</description>
					</alertTemplate>
				</document>`;
	},
	// pass some raw data to be applied
	// or a data function that returns the data
	data: {
		title: 'Homepage',
		description: 'This is my super awesome homepage created using atvjs.'
	}
});

// later in your application you can do something like below to navigate to the page
ATV.Navigation.navigate('home');

<a name="adding-tvml-styles-to-your-page"></a>

Adding TVML styles to your page

You need to define your TVML styles as string and pass that as a configuration to your page. It will automatically be added to your page document in the runtime when your page is being navigated.

let myPageStyles = `
.text-bold {
	font-weight: bold;
}
.text-white {
	color: rgb(255, 255, 255);
}
`;

ATV.Page.create({
	name: 'home',
	style: myPageStyles,
	template: your_template_function,
	data: your_data
});

<a name="fetching-data-from-a-remote-source"></a>

Fetching data from a remote source

You can fetch JSON content from the remote api by setting the url configuration. The data will be fetched using ajax and will be applied to the provided template. You can even run some transformations on the data before applying it to the template

ATV.Page.create({
	name: 'home',
	url: 'path/to/your/api/that/returns/json',
	template: your_template_function
});

// or you can transform the response before applying to your template
ATV.Page.create({
	name: 'home',
	url: 'path/to/your/api/that/returns/json',
	template: your_template_function,
	data(response) {
		// transform your response before applying to your template
		let transformedData = someTransformationOfResponse(response);
		return transformedData;
	}
});

<a name="creating-links-to-other-pages"></a>

Creating links to other pages

You can setup links to other pages directly in your TVML markup by setting the data-href-page attribute with the value of your page name that you want to link to. The framework will take care of the navigation for you. You can also pass options to your page (see topic Custom options while navigation for details) by setting up the data-href-page-options attribute with a JSON value.

<document>
	<alertTemplate>
		<title>Example for creating links to other pages</title>
		<description>Select an option</description>
		<button data-href-page="homepage">
			<text>Go To Homepage</text>
		</button>
		<button data-href-page="login" data-href-page-options='{"username": "emadalam", "password": "123456"}'>
			<text>Login</text>
		</button>
	</alertTemplate>
</document>

<a name="advanced-topics"></a>

Advanced Topics

<a name="event-handling"></a>

Event Handling

You can define the list of events and their respective handlers as key-value pairs. The handler will be invoked in the current object context and you can access all the methods and properties that exist on the object.

ATV.Page.create({
	name: 'mypage',
	template: your_template_function,
	data: your_data,
	events: {
		select: 'onSelect',
		highlight: 'onHighlight'
	},
	// method invoked in the scope of the current object and
	// 'this' will be bound to the object at runtime
	// so you can easily access methods and properties and even modify them at runtime
	onSelect(e) {
		let element = e.target;
		let someCheckForElementType = element.getAttribute('data-my-attribute');
		let someOtherCheckForElementType = element.getAttribute('data-my-other-attribute');