MediaMatrix API Documentation

MatrixStreamMediaMatrix API

DocumentionVersion 1.0

CONFIDENTIAL

IndexRevision History.....................................................................................................................3Summary................................................................................................................................4XML Page Specification.........................................................................................................5

Doctype Declaration........................................................................................................................5Page Tags..............................................................................................................................6

page..................................................................................................................................................6title...................................................................................................................................................6body.................................................................................................................................................7

Object Tags............................................................................................................................8Label Tag.........................................................................................................................................9Textbox Tag...................................................................................................................................10Image Tag.......................................................................................................................................11Link Tag.........................................................................................................................................12

Form Tags............................................................................................................................13Form Tag........................................................................................................................................13Checkbox Tag................................................................................................................................14Radio Tag.......................................................................................................................................15Selection Tag..................................................................................................................................17Keyboard Tag.................................................................................................................................18Button Tag......................................................................................................................................20

Example Page......................................................................................................................21

CONFIDENTIAL

Revision History

Date Version Number28/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.

pageMarks the root element of the XML document. Also contains namespace information

and the background color for the page.

xmlns attributeXML 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 attributeThe 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>

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

IconIcon 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>

bodyThe body tag encapsulates any object tags that make up the page. These include

labels, textboxes, images, links, and form objects.

e.g.<body>

</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.

topThe number of pixels from the top of the page. Screen range is 0 - 540.leftThe number of pixels from the left of the page. Screen range is 0 - 960.widthThe width of the object.heightThe height of the object.bgcolorThe 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.

fontsizeThe vertical size of the font in pixels.fontcolorThe color value for the font.textalignHorizontally 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.

fontsizeThe vertical size of the font in pixels.fontcolorThe color value for the font.textalignHorizontally alignment of the text. Valid values include: left, center, and right. By


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.

srcThe URL to the image. Used to download the image to display.drawmodeThe 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).

gotoThe 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.

idThe identifier for the group of form controls the concatinated controls belong to.

Example:<form id="UID">

</form>

<form id="UID">

</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.

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


<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.

groupThe group the control belongs to. Also treated as the value name when sent back

as a POST value.valueThe control-specific value associated with the control being enabled when sent back

as a POST value.checkedBoolean value for whether to enable by default. Default is false.colorThe color of the check (for on).


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.

nameThe name of the control to send back as the POST parameter.inputsA 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.".


<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.

nameThe name of the control to send back as the POST parameter.fontsizeThe vertical size of the font in pixels.fontcolorThe color value for the font.textalignHorizontally alignment of the text. Valid values include: left, center, and right. By



<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.

nameThe name of the control to send back as the POST parameter.fontsizeThe vertical size of the font in pixels.fontcolorThe color value for the font.


<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

MediaMatrix API Documentation

Documents

Transcript of MediaMatrix API Documentation