MatrixStream

MediaMatrix API
Documention
Version 1.0

CONFIDENTIAL
Index
Revision History.....................................................................................................................3
Summary................................................................................................................................4
XML Page Specification.........................................................................................................5
Doctype Declaration........................................................................................................................5
Page Tags..............................................................................................................................6
page..................................................................................................................................................6
title...................................................................................................................................................6
body.................................................................................................................................................7
Object Tags............................................................................................................................8
Label Tag.........................................................................................................................................9
Textbox Tag...................................................................................................................................10
Image Tag.......................................................................................................................................11
Link Tag.........................................................................................................................................12
Form Tags............................................................................................................................13
Form Tag........................................................................................................................................13
Checkbox Tag................................................................................................................................14
Radio Tag.......................................................................................................................................15
Selection Tag..................................................................................................................................17
Keyboard Tag.................................................................................................................................18
Button Tag......................................................................................................................................20
Example Page......................................................................................................................21

CONFIDENTIAL
Revision History

Date Version Number

28/10/10 1.0

CONFIDENTIAL
Summary

The MediaMatrix API has been designed to add extensibility to the set top box.
Through the use of the API, it is possible to create simple customized pages or features for
user interaction. Furthermore, pages can be generated to include dynamic content through
the use of server-side scripting languages such as PHP or ASP.NET. The API works
through a simple XML standard.

CONFIDENTIAL
XML Page Specification

The MediaMatrix API XML is built out of XML tags describing a page; using XML
tags to define objects on the screen. Some examples of the tags usable in the API include
labels, images, links, checkboxes, buttons, and more. These tags can be split into three
categories: page tags, object tags, and form tags.

Page tags define the page itself.

Object tags define the contents within the page.
Form tags are a branch of object tags which are used to make POST requests.

Doctype Declaration

The doctype declaration tag is the first line in the XML document. It defines the XML
version (1.0) and the encoding used (utf-8).

e.g.
<?xml version="1.0" encoding="utf-8"?>

CONFIDENTIAL
Page Tags

The Page tags are used to define the overall structure of the page. The main page
tag acting as the root element in the XML document, with the title tag defining the page's
title display information.

page
Marks the root element of the XML document. Also contains namespace information
and the background color for the page.

xmlns attribute
XML Name Space this identifies that this document follows the XML standard
defined by MatrixStream. The XML name space is important for validating an XML
document before deploying it to your server for the set top box to use.

bgcolor attribute
The background color of the page. . If used it will set the color and alpha values for
the page's background. bgcolor must be specified as a hex string with a length of 8 digits,
and start with 0x. bgcolor is formatted as: 0xAARRGGBB, with A being Alpha for
transparency, R being level of red for color, G being level of green for color, and B being
level of blue for color. A valid bgcolor string would be: "0xFF003300" (dark green, fully
visible).

e.g.
<page xmlns="http://www.matrixstream.com" bgcolor="0x88000000">
<!-- Page Items -->
</page>

title
The title tag provides the page with a title and an icon.

Icon
Icon can contain a URL to a png, jpg, or gif located on a web server. The image will
then be downloaded and used to represent the page next to the title text.

CONFIDENTIAL
 e.g.
<title icon="http://www.hostname.com/icon.gif">this is my title</title>

body
The body tag encapsulates any object tags that make up the page. These include
labels, textboxes, images, links, and form objects.

e.g.
<body>
<!-- Page Object Here -->
</body>

CONFIDENTIAL
Object Tags

Object tags are used to describe the contents of a page. Each tag defines a
separate control or instance of a control to be positioned on the page. As such, there are
several properties shared among objects: top, left, width, height, and bgcolor.

top
The number of pixels from the top of the page. Screen range is 0 - 540.
left
The number of pixels from the left of the page. Screen range is 0 - 960.
width
The width of the object.
height
The height of the object.
bgcolor
The background color of the object.

CONFIDENTIAL
Label Tag

The label tag adds a single line text body to the page. Any text that exceeds the
total width of the body will be cropped then concatinated with "...". In addition to the
standard object attributes, label contains fontsize, fontcolor, and textalign. Text placed
inside the tag will be displayed.

fontsize
The vertical size of the font in pixels.
fontcolor
The color value for the font.
textalign
Horizontally alignment of the text. Valid values include: left, center, and right. By
default, textalign is set to left.

Example:
<label top="0" left="0" width="960" height="540" bgcolor="0x00000000"
fontsize="14" fontcolor="0xFF000000" textalign="Center">
Lorem ipsum dolor sit amet.</label>

CONFIDENTIAL
Textbox Tag

The textbox tag allows for multi-line text bodies to be placed on the page. Like the
label tag, the textbox tag also contains fontsize, fontcolor, and textalign.

fontsize
The vertical size of the font in pixels.
fontcolor
The color value for the font.
textalign
Horizontally alignment of the text. Valid values include: left, center, and right. By
default, textalign is set to left.

Example:
<textbox top="0" left="0" width="960" height="540" bgcolor="0x00000000"
fontsize="14" fontcolor="0xFF000000" textalign="Center">
Lorem ipsum dolor sit amet.</textbox>

CONFIDENTIAL
Image Tag

The image tag places an image body then makes a download request on an image
placed on a server. Once downloaded, it loads the images into the body. In addition to the
standard object attributes, image contains src and drawmode.

src
The URL to the image. Used to download the image to display.
drawmode
The mode for drawing the image. Valid values include normal, stretch, scale, and
scalecentered. By default drawmode is set to normal.

Example:
<image top="0" left="0" width="960" height="540" bgcolor="0x00000000"
src="http://192.168.1.100/img.jpg" drawmode="Center"></image>

CONFIDENTIAL
Link Tag

The link tag encapsulates a object tag, registering it for input. There can be multiple
links on a page, allowing for menus and letting the user select between multiple pages.
Links do not contain the standard object tags, instead containing a goto attribute.

When the user is on a page containing links, they will be able to move forward and
backward through the links and be able to select them in order to load a new page
(specified by the links).

goto
The goto tag specifies the URL of the page to load when selected.

Example:
<link goto="http://192.168.1.100/page1.php">
<label top="0" left="0" width="960" height="270" bgcolor="0x00000000"
textalign="Center">This is made clickable.</label>
</link>

<link goto="http://192.168.1.100/page2.xml">
<image top="270" left="0" width="960" height="270" bgcolor="0x00000000"
src="http://192.168.1.100/img.jpg" drawmode="Center"></image>
</link>

CONFIDENTIAL
Form Tags

Form tags, like object tags, describe contents of a page. However, unlike object
tags, form tags offer a wider array of options for receiving and sending user input. Some of
the common controls offered in form tags allow for user inputted text, toggleable
selections, and form posts sent to the server.

Form tags are always encapsulated by a form tag which contains an ID of the form.
You can have multiple forms with multiple IDs placed on a page, but only forms sharing an
ID to that containing the button the user clicks will send their data.

Form Tag

The form tag must encapsulate a form object (checkbox, radio, selection, keyboard,
or button). On adding a form item, it will automatically be registered for user input. Form
includes one attribute: id.

id
The identifier for the group of form controls the concatinated controls belong to.

Example:
<form id="UID">
<!-- Form Controls Here -->
</form>

<form id="UID">
<!-- Form Controls Here -->
</form>

CONFIDENTIAL
Checkbox Tag

Checkboxes provide a simple toggle-able control, returning either true (if on) or
false (if off). Checkboxes contain the standard object attributes, as well as name, checked,
and color.

name
The name of the control to send back as the POST parameter.
checked
Boolean value for whether to enable by default. Default is false.
color
The color of the check (for on).

Example:
<form id="UID">
<checkbox top="0" left="0" width="960" height="540" bgcolor="0xFFFFFFFF"
name="CheckBox1" checked="false"
color="0xFF000000"></checkbox>
</form>

CONFIDENTIAL
Radio Tag

Radio defines a toggleable control within a group of radio tags. Each radio button
belongs to a group, and only one radio button per group can be enabled at a time
(disabling the others when enabled). Radio buttons contain the standard object attributes,
as well as group, value, checked, and color.

group
The group the control belongs to. Also treated as the value name when sent back
as a POST value.
value
The control-specific value associated with the control being enabled when sent back
as a POST value.
checked
Boolean value for whether to enable by default. Default is false.
color
The color of the check (for on).

Example:
<form id="UID">

CONFIDENTIAL
 <radio top="0" left="0" width="960" height="540" bgcolor="0xFFFFFFFF"
group="Radios" value="Rad1" checked="true"
color="0xFF000000"></radio>
<radio top="0" left="0" width="960" height="540" bgcolor="0xFFFFFFFF"
group="Radios" value="Rad2" checked="false"
color="0xFF000000"></radio>
<radio top="0" left="0" width="960" height="540" bgcolor="0xFFFFFFFF"
group="Radios" value="Rad3" checked="false"
color="0xFF000000"></radio>
</form>

CONFIDENTIAL
Selection Tag

Selection controls allow the user to choose between multiple values for a single
control. Selection controls contain the standard object attributes, as well as name and
inputs.

name
The name of the control to send back as the POST parameter.
inputs
A string of inputs to give the control: separated by spaces. Can contain a variable
number of options, each one MUST be separated by a space. Eg: "Lorem ipsum dolor sit
amet, consectetur adipiscing elit.".

Example:
<form id="UID">
<selection top="0" left="0" width="960" height="540" bgcolor="0xFFFFFFFF"
name="selection" inputs="1 2 3 4 5 6 7 8 9 10 11 12"></selection>
</form>

CONFIDENTIAL
Keyboard Tag

The Keyboard form object allows the user to input text to be received as a POST
request. When the Keyboard object is placed, it registers a label for input, which when
selected creates an on-screen keyboard. Keyboard contain the standard object attributes,
as well as name. In addition, the generated label can be customized using the fontsize,
fontcolor, and textalign attributes.

name
The name of the control to send back as the POST parameter.
fontsize
The vertical size of the font in pixels.
fontcolor
The color value for the font.
textalign
Horizontally alignment of the text. Valid values include: left, center, and right. By
default, textalign is set to left.

Example:
<form id="UID">
<keyboard top="0" left="0" width="960" height="540"

CONFIDENTIAL
bgcolor="0x00000000" name="Keyboard" fontsize="14"
fontcolor="0xFF000000" textalign="Center"></keyboard>
</form>

CONFIDENTIAL
Button Tag

Button tags are used when you wish to receive form control inputs. Selecting a
button that belongs to a form will load the page specified by the button; all form controls
inside the matching form ID will be sent as POST data to the page. Button contain the
standard object attributes, as well as name. In addition, the text displayed on the button
can be customized using fontsize, and fontcolor attributes, with the text to display placed
inside the tag.

name
The name of the control to send back as the POST parameter.
fontsize
The vertical size of the font in pixels.
fontcolor
The color value for the font.

Example:
<form id="UID">
<button top="0" left="0" width="960" height="540" name="Button1"
fontsize="14" fontcolor="0xFF000000">Click Me</button>
</form>

CONFIDENTIAL
Example Page

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

<page xmlns="http://www.matrixstream.com" bgcolor="0x88000000">

<title icon="http://HOSTNAME/hotel_icon_titlebar.png">MediaMatrix API Demo</title>

<body>
<link goto="http://HOSTNAME/hotel_information.xml">
<label top="130" left="120" width="300" height="40"
bgcolor="0x00000000"
fontsize="22" fontcolor="0xFFFFFFFF"
textalign="Center">Hotel Information</label>
</link>

<link goto="http://HOSTNAME/Room_Service/room_service.php">
<label top="180" left="120" width="300" height="40"
bgcolor="0x00000000"
fontsize="22" fontcolor="0xFFFFFFFF"
textalign="Center">Room Service</label>
</link>

<link goto="http://HOSTNAME/Room_Features/room_features.php">
<label top="230" left="120" width="300" height="40"
bgcolor="0x00000000"
fontsize="22" fontcolor="0xFFFFFFFF"
textalign="Center">Room Features</label>
</link>

<link goto="http://HOSTNAME/Weather_Forcast/weather2.php">
<label top="330" left="120" width="300" height="40"
bgcolor="0x00000000"
fontsize="22" fontcolor="0xFFFFFFFF"
textalign="Center">Weather Forcast</label>
</link>

<image src="http://HOSTNAME/stblogo.png"
top="180" left="460" width="356" height="112"
bgcolor="0x00000000"
drawmode="ScaleCenter" />
</body>
</page>

CONFIDENTIAL