Chapter 2. XML and JavaScript Overview

The following sections provide a brief overview of XML and JavaScript programming which is used in TV Apps. This tutorial does not cover all of the aspects of XML and JavaScript that are required to be successful writing TV Apps. XML and JavaScript are both well-documented on the Internet and in various computer programming manuals. If you are new to these languages please use the following overview as a starting point for your own research in these subjects.

Using XML for TV App Metadata

XML is used to define the app’s starting point (main program) and to define its metadata. XML stands for eXtensible Markup Language and is designed to store and transport data. You may be familiar with HTML, which is also a markup language, but unlike HTML, XML is not designed for display purposes. To simplify, XML focuses on what the data is; HTML focuses on how the data looks.

Two XML files are required for TV Apps:

  • The main.TV file is the starting point of the app (the main program) and is the first file executed by the Engine. This file typically includes external JavaScript files for the app which define the app’s functionality. The .TV file extension for the main.TV file must be capitalized or the app will not load.
  • The widget.xml file describes the app’s metadata. This file specifies information about your app such as the name of the app, author, organization, copyright information, and any security metadata.

See the Review the Sample TV App Files section for more information.

XML Elements

When you open an XML file, the first line in the file is the XML declaration. For example:

<?xml version="1.0" encoding="UTF-8"?>

This declaration defines the XML version (1.0) and the character encoding (utf-8 is the 8-bit UCS/Unicode Transformation Format). The next line, and the last line, in the XML file describes the root element of the document (in the TV App case use the element <widget></widget> in the main.TV file and the element <metadata></metadata> for widget.xml file). After the root element, the enclosed lines in the XML file describe child elements of the root element.

A single XML element includes everything from the element’s start tag to the element’s end tag. An XML element can contain other elements, simple text, or a mixture of both. XML elements must be properly nested. Elements can have attributes whose values must be quoted. Finally all XML elements must have a closing tag. XML tags are case sensitive so opening and closing tags must be written with the same case. For example, review the element nesting in this sample file:

File widget.xml

XML Element Naming Rules

XML elements must follow these naming rules:

  • Names can contain letters, numbers, and underscores .
  • Names must not start with a number or punctuation character.
  • Names must not start with the letters xml (or XML, or Xml, or any other permutation).
  • Names cannot contain spaces.
  • Any name can be used, no words are reserved.
  • Lowercase naming is used by TV Apps for the Engine.

Special Characters

When including text or strings in XML, be sure to replace special characters with the following entity references:

Character XML Replacement Description
< &lt; less than
> &gt; greater than
& &amp; ampersand
' &apos; apostrophe
" &quot; quotation mark

Also use the special characters when including JavaScript in XML. Because the XML parser looks for the < and > symbols to mark blocks of XML data, the Engine's JavaScript engine needs to have these symbols replaced with &lt; and &gt; respectively. For example:

Alternatively, you can put the JavaScript code inside CDATA sections to prevent the XML parser from looking at them. This is a better solution for larger blocks of code.

You can also avoid the XML parser looking at your JavaScript entirely by putting it in a separate .js file and importing it, via the src attribute:

<script src="myFile.js" />

XML Comments

Comments in XML are the same as comments in HTML:

<!-- This is an XML comment -->

Table of Contents