JavaScript API

From DevWiki

Jump to: navigation, search

Back to Home

Contents



Preface

The new Boxee client has a builtin webkit based browser (qt flavor). In general that browser always renders “offscreen” and boxee is responsible for taking that offscreen snapshot and presenting it to the user. Several content-types are associated with the builtin browser so that it is launched whenever web content is to be consumed.

Once launched, the boxee browser will look for a “controller script”. That script (written in javascript) contains information on how to render the page and is used to “orchestrate” the page’s playback.

Previous version of Boxee contained a mozilla based browser and although it used the same mechanism for web content playback, there are some fundamental changes in the API and flows in the current Boxee version.

This document describes the developer API of the current Boxee client’s embedded browser.


Backward Compatibility

The new browser tries to be backward compatible and accommodate scripts that were written to older versions of the browser. In order to specify that a specific script was written for the new browser, specify the following: 

  1. boxee.apiMinVersion=7.0;

This will cause the browser to set the defaults correctly. For example - automatically choosing the player is switched off by default.


Examples

The scripts listed below do not necessarily work for, nor are they intended for any particular site. They are simply examples to assist in the learning process. We will add more here as needed.


External Resources


Builtin Objects

A few Javascript objects are predefined and should be used to control how a page “executes”.

boxee

The boxee object contains:

browser

The browser object contains functions for interacting with the current web page (executing javascript, simulating mouse and keyboard events, etc...)

playerState

This is a new object (introduced in version 7.0 of the API) that holds information on the current state of the player (active controls, extensions, playback state, etc...)


Browser OSD

Whenever a user clicks on "menu", the browser’s OSD shows up. Before the OSD shows up, the playerState object is queried so that the OSD will reflect the current state. This way, interval polling that is used in many older scripts can be avoided.

The recommended way for a script to send information to boxee is simply by setting playerState variables.

The onUpdateState handler is introduced in version 7.0 of the API that is called just before the OSD shows up to allow the script to set playerState variables. Example: 

  1. boxee.onUpdateState = function() { /* code */ }


Browser Modes

The browser currently has 3 main modes of operations, 4 total:

Cursor Mode

In this mode, the browser shows a cursor and allows cursor navigation using the remote controls arrow buttons. Clicking on links will follow them and clicking on edit fields will open up boxee’s keyboard dialog. Whenever the cursor hovers over an edit field it becomes focused so that input from the keyboard is passed directly to the control.

This is the default mode of operation.

To set this mode, call: 

  1. boxee.setMode(boxee.CURSOR_MODE);

When in cursor mode, a few handlers can be implemented to change the default behavior:

boxee.onMouseMoveDown

if this handler exists, it will be called when the used hits “down” (instead of moving the mouse down). 

  1. boxee.onMouseMoveDown = function() { boxee.log('User pressed Down'); }

All mouse handlers responding to the same logic:

Keyboard Mode

In this mode of operation, remote control navigation is translated to arrow keys. For example if the user hits the remote’s “up” button, the browser will act as if “arrow up” was pressed on the keyboard. This mode is very useful for various sites that were designed with 10ft UI in mind (e.g. youtube leanback). To set this mode, call: 

  1. boxee.setMode(boxee.KEYBOARD_MODE);

When in keyboard mode, a few handlers can be implemented to change the default behavior:

boxee.onKeyboardKeyDown

if this handler exists, it will be called when the used hits “down” (instead of sending “arrow down” to the browser). 

  1. boxee.onMouseMoveDown = function() { boxee.log('User pressed Down'); }

All keyboard handlers responding to the same logic:

Additionally the Back button (Menu button on the remote, Esc key on a keyboard) can be overridden:

boxee.onKeyboardKeyBack

However, this will prevent a user from exiting an app without rebooting, unless the app calls browser.shutdown()

If onKeyboardKeyBack is used, your app must allow the user to easily trigger a browser.shutdown()

Player Mode

When in player mode, the remote-control’s navigation keys translate to player actions.

To set this mode, call: 

  1. boxee.setMode(boxee.PLAYER_MODE);

The user can not override the behavior in Player Mode (for that matter, up/down will always control the volume). However, the user does need to provide handlers for available OSD actions:

Locked Player Mode

This is the same as Player Mode, however the user can not go back to the browser page and can not activate the cursor. It is essentially like regular playback mode. To set this mode, call: 

  1. boxee.setMode(boxee.LOCKED_PLAYER_MODE);


Control Scripts

Control scripts are called on by the Boxee player and used to manage playback functionality. These scripts can be defined in different ways and can be located in different places. When a the player loads a url, it will look for scripts in the following places/order:

bx-jsactions

1. specified in flash:// protocol media link
If using the flash potocol (flash://) for media links, the bx-jsactions parameter can be used to specify the URL for the control script to be loaded. Notice the bx-jsactions param in the example below.
See the Boxee RSS Specifications for more details on how to construct a proper link using the flash protocol.
flash://joost.com/src=http%3A%2F%2Fjoost.com%2Fembed%2F13600&bx-jsactions=http%3A%2F%2Fmyserver%2Fcontrol.js

boxee server

3. Default location scripts created by boxee devs
Does not load if bx-jsactions is specified or loaded locally.
The Boxee server uses a number of methods to find a proper control script, including the domain from the url provided. These are scripts are written and managed by Boxee developers.

metadata tag

4. if available, will always be loaded
A control script url can be specified by web developers in the <head> tag of any page.
If exists, this script will load regardless of any others that may have already been loaded. Can be used to override predefined scripts. 
  1. <meta name="boxee-control" content="http://mysite.com/boxee/mysite.js" />

object src

4. loaded if no script was found before
If no control scripts have been located up to this point, Boxee will load the url and attempt to automatically locate the proper object on the page. (flash, silverlight, etc..)
If an object is found (<object> or <embed> tags), boxee will then look for the src or data attribute in that object.
Once found, the player will again check first locally, then on the boxee servers for the proper script. 
  1. <embed src="http://cdn.episodic.com/player/EpisodicPlayer.swf?pid=294" />


Testing & Debugging

Currently there is no way to monitor javascript/browser output on devices such as the Boxee Box. We are actively working on developing a way for developers to obtain this output and will update the client as soon as its available.


"boxee" Web Object

Whenever a page is loaded in boxee’s embedded browser, a javascript object called “boxee” becomes available for scripts running on this page. This objects exports a single method: “exec”, which executes javascript code - inside the “javascript controller”.

This is very powerful in several ways: A site can... 

  1. boxee.exec('boxee.onPause = function() { browser.execute("document.player.pause()"); }')

This object will be wrapped with easier to use javascript functions in future releases.


Screen Modes

On embedded platforms, boxee supports the “real full screen” playback mode of flash. Many of the times, the control's layout is different between fake full screen and real full screen, which may cause problems with scripts that simulate clicks and mouse moves.

In order for the developer to control which full screen mode is used, a second (boolean) parameter to "setActive" is introduced. If it is set to "true" then boxee will try to activate the "real full screen" mode of the flash player. Note that setActive only applies when a flash object is manually selected.

This behavior can also be controlled by a new boolean boxee variable called “realFullScreen”.


boxee Object

Constants

Modes are define above in section 6.


Variables

realFullScreen

realFullScreen:Boolean
Controls the default full screen mode. see screen modes 

  1. boxee.realFullScreen = true;
renderBrowser

renderBrowser:Boolean
Controls whether the complete web page is shown or not 

  1. boxee.renderBrowser = true;
apiMinVersion

apiMinVersion:Number
Affects default values. For scripts utilizing the latest functionality it should be set to "7.0". 

  1. boxee.apiMinVersion = 7.0;
autoChoosePlayer

autoChoosePlayer:Boolean
Controls whether the browser should automatically pick the playing video from the page and present it full screen (skipping the web page phase). the default has changed in version 7.0 and is now "false". 

  1. boxee.autoChoosePlayer = true;
browserWidth

browserWidth:Number
Controls the size which the browser should open up to. Default is 1280. Remember that browser size can affect performance. 

  1. boxee.browserWidth = 853;
browserHeight

browserHeight:Number
Controls the size which the browser should open up to. Default is 720. Remember that browser size can affect performance. 

  1. boxee.browserHeight = 480;
useBoxeeCookies

useBoxeeCookies:Boolean
Controls whether to import the cookies from boxee so that they are available to the web page. This is useful when the page is launched from a script after already performing some HTTP transactions (e.g. login) using the built-in python modules. The default has changed in version 7.0 and is now set to "true". 

  1. boxee.useBoxeeCookies = false;
autoChooseRepeat

autoChooseRepeat:Boolean
If set to "true", boxee will repeatedly try and pick the playing video from the web page. This is useful in web pages that change the player (e.g. during commercials). this value is only used if "autoChoosePlayer" is set to "true". 

  1. boxee.autoChooseRepeat = true;
reloadOnPageChange

reloadOnPageChange:Boolean
If set to "true", will re-fetch and evaluate the domain’s JavaScript controller when navigating to a new web page. mind that the default is "false". 

  1. boxee.reloadOnPageChange = true;
showOSDOnStartup

showOSDOnStartup:Boolean
Show OSD when browser is first launched, default is true. 

  1. boxee.showOSDOnStartup = false;

Functions

getVersion

getVersion():Number
Returns the current api version. 

  1. boxee.getVersion();
enableLog

enableLog(allowLogging:Boolean):Void
This function switches logging on or off. 

  1. boxee.enableLog(true);
log

log(message:String):Void
If logging is enabled, this will output the message to standard error or as "OutputDebugString" on win32. Currently there is no valid way to obtain JavaScript debug logs from the Boxee Box, but is something we are currently working on. 

  1. boxee.log('this is a test!');
setMode

setMode(mode:Integer):Void
Changes the browser's mode of operation. see "Browser Modes" in section 6. 

  1. boxee.setMode(boxee.KEYBOARD_MODE);
notifyConfigChange

notifyConfigChange(width:Integer, height:Integer):Void
Tells the boxee client that the width and height of the display should change (for example - when scaling a player to full screen). This function does nothing on embedded platforms. 

  1. boxee.notifyConfigChange(720, 1280);
getWidgets

getWidgets(width:Integer, height:Integer):Array
Returns an array of all widgets known to the browser. Widget is an <embed>, <object> or <video> element on the page. see "Widget" 

  1. boxee.getWidgets();
getActiveWidget

getActiveWidget():Widget
If one of the widgets is now the active one (shown full screen), this function will return it 

  1. boxee.log(boxee.getActiveWidget().height);
notifyPlaybackEnded

notifyPlaybackEnded():Void
Tells boxee that playback is done and the browser should be closed 

  1. boxee.notifyPlaybackEnded();
getHttp

getHttp(url:String):String
Issues an "HTTP GET" on the provided URL and returns the result's body (the URL should contain text) 

  1. boxee.getHttp();
getCurrentLocation

getCurrentLocation():String
Returns the browser’s current URL 

  1. url = boxee.getCurrentLocation();
getParam

getParam(param:String):String
When the browser is launched, several parameters are set by the system and others are set by the launch command (if it was launched as "flash://"). The only valid system parameter at the moment is "src" which contains the original url that the browser was launched with. 

  1. source = boxee.getParam('src');
getPlatform

getPlatform():String
Returns the current platform.

"MacIntel" on mac, "appletv" on apple-tv, "dsm380” on boxee box, "Linux" on linux, "Win32" on windows 
  1. platform = boxee.getPlatform();
loadJS

loadJS(url:String):Void
Loads and evaluates the JavaScript at the provided URL. 

  1. boxee.loadJS('http://mysite.com/boxee/js/mysite.js');
showNotification

showNotification(message:String, thumbUrl:String, durationInSeconds:Integer):Void
Makes boxee show a popup notification. In pre 7.0 versions the popup is displayed in the top left, however in versions >= 7.0 the popup displays in the top right. 

  1. boxee.showNotification("This video is available in HD", ".", 3);
getTextInput

getTextInput(title:String, callbackFunction:String):Void
Launch boxee's keyboard OSD and assign a callback for the input. 

  1. boxee.getTextInput("this is the title", "OnUserInput");
  2.  
  3. function OnUserInput(inputText, confirmed) {
  4.   if (confirmed)
  5.     alert("user entered: "+inputText);
  6.   else
  7.     alert("user cancelled...");
  8. }
launchInspector

launchInspector():Void
This is very useful for debugging, it will launch the builtin webkit inspector (the complete inspector, including javascript console). 

  1. boxee.launchInspector();
dumpWidgets

dumpWidgets():Void
If logging is enabled, this will dump information on all available widgets 

  1. boxee.dumpWidgets();
dumpActiveWidget

dumpActiveWidget():Void
If logging is enabled, this will dump information on the active widget (if there is one) 

  1. boxee.dumpActiveWidget();
callBoxeeBuiltin

callBoxeeBuiltin(builtinFunction:String):Void
Activates a builtin function in boxee, the exact same way as it is used from skin. See boxee’s UI documentation for more available actions. 

  1. boxee.callBoxeeBuiltin("ActivateWindow(NetworkSettings)");
showBoxeeOSD

showBoxeeOSD():Void
Reveals the Boxee OSD. 

  1. boxee.showBoxeeOSD();
autoSelectPlayer

autoSelectPlayer():Void
Tries to locate a player on the page (among the available widgets) and if one is found - automatically set it as active. 

  1. boxee.autoSelectPlayer();


Handlers

All functions that are called on various events (hooks).

onInit
Called after the browser is created, just before it navigates to the first page. 
  1. boxee.onInit = function() {}
onDocumentLoading
Called whenever a page starts loading 
  1. boxee.onDocumentLoading = function() {}
onDocumentLoaded
Called when the page had finished loading 
  1. boxee.onDocumentLoaded = function() {}
onNotifyUrl

onNotifyUrl():String
Called whenever a url resource is loaded by the web page. receives the url as a string parameter. 

  1. boxee.onNotifyUrl = function(url) { alert(url); }
onUpdateState
Called just before the browser’s OSD is shown. to allow setting the playerState correctly. 
  1. boxee.onUpdateState = function() {}
onEnterFullScreen
Called when the user requested that the player will go to full screen. if this handler exists, it is expected to cause the player to switch to full screen (the default action will not be executed). 
  1. boxee.onEnterFullScreen = function() {}
onExitFullScreen
Called when the user requested to leave full screen playback. if this handler exists then the default action will not be executed and the handler is expected to cause the player to leave full screen. 
  1. boxee.onExitFullScreen = function() {}
onPause
Called when the user requested that the video will be “paused”. this handler is expected to actually pause the video. 
  1. boxee.onPause = function() {}
onPlay
Called when the video should be resumed. the handler is expected to resume the video. 
  1. boxee.onPlay = function() {}
onSeekTo
Called when the user requested a short skip forward. the handler is expected to perform that skip.
It is important to note here that for this to work correctly playerState.time and playerState.duration should be set within boxee.onUpdateState 
  1. boxee.onSeekTo = function(milliseconds) { browser.execute('myObject.seek(' + milli/1000 + ')'); }
onSkip
Called when the user requested a short skip forward. the handler is expected to perform that skip. 
  1. boxee.onSkip = function() {}
onBigSkip
Called when the user requested a big skip forward. the handler is expected to perform that skip. 
  1. boxee.onBigSkip = function() {}
onBack
Called when the user requested a short jump backwards. the handler is expected to perform this jump. 
  1. boxee.onBack = function() {}
onBigBack
Called when the user requested a big jump backwards. the handler is expected to perform this jump. 
  1. boxee.onBigBack = function() {}
onKeyboardKeyUp
Called when in KEYBOARD_MODE and “up” was clicked. if this handler exists - the default action will not execute. 
  1. boxee.onKeyboardKeyUp = function() {}
onKeyboardKeyDown
Called when in KEYBOARD_MODE and “down” was clicked. if this handler exists - the default action will not execute. 
  1. boxee.onKeyboardKeyDown = function() {}
onKeyboardKeyLeft
Called when in KEYBOARD_MODE and “left” was clicked. if this handler exists - the default action will not execute. 
  1. boxee.onKeyboardKeyLeft = function() {}
onKeyboardKeyRight
Called when in KEYBOARD_MODE and “right” was clicked. if this handler exists - the default action will not execute. 
  1. boxee.onKeyboardKeyRight = function() {}
onKeyboardKeyEnter
Called when in KEYBOARD_MODE and “enter” (select) was clicked. if this handler exists - the default action will not execute. 
  1. boxee.onKeyboardKeyEnter = function() {}
onMouseMoveUp
Called when in CURSOR_MODE and is supposed to move the mouse up. it overrides the default behavior (if exists). 
  1. boxee.onMouseMoveUp = function() {}
onMouseMoveDown
Called when in CURSOR_MODE and is supposed to move the mouse down. it overrides the default behavior (if exists). 
  1. boxee.onMouseMoveDown = function() {}
onMouseMoveLeft
Called when in CURSOR_MODE and is supposed to move the mouse left. it overrides the default behavior (if exists). 
  1. boxee.onMouseMoveLeft = function() {}
onMouseMoveRight
Called when in CURSOR_MODE and is supposed to move the mouse right. it overrides the default behavior (if exists). 
  1. boxee.onMouseMoveRight = function() {}
onMouseClick
Called when in CURSOR_MODE and click was performed. it overrides the default behavior (if exists). 
  1. boxee.onMouseClick = function() {}


browser

Functions

execute

execute(expression:String):String
Execute JavaScript expression on the current web page. 

  1. isPlaying = browser.execute('document.player.isVideoPlaying();');
navigate

navigate(url:String):Void
Navigate to a given url. 

  1. browser.navigate();
mouseMove

mouseMove(x:Integer, y:Integer):Void
Moves mouse pointer to a specified location. 

  1. browser.mouseMove(500, 160);
click

click(x:Integer, y:Integer):Void
Simulates a mouse click at the specified location. 

  1. browser.click(500, 160);
mouseDown

mouseDown(x:Integer, y:Integer):Void
Simulates a mouse down event at the specified location. 

  1. browser.mouseDown(500, 160);
mouseUp

mouseUp(x:Integer, y:Integer):Void
Simulates a mouse up event at the specified location. 

  1. browser.mouseUp(500, 160);
keyPress

keyPress(keyCode:Integer):Void
Simulates a key press event in the browser.

List of available keyCodes 
  1. browser.keyPress(13);
keyUp

keyUp(keyCode:Integer):Void
Simulates a key up event in the browser.

List of available keyCodes 
  1. browser.keyUp(13);
keyDown

keyDown(keyCode:Integer):Void
Simulates a key down event in the browser.

List of available keyCodes 
  1. browser.keyDown(13);
setCookie

setCookie(domain:String, key:String, value:String):Void
Sets a cookie in the browser. 

  1. browser.setCookie('youtube.com', '_somekey', 'somevalue');
getLocation

getLocation():String
Asks the browser for the current URL 

  1. currentUrl = browser.getLocation();
mouseWheelLeft

mouseWheelLeft():Void
Simulates mouse wheel left. 

  1. browser.mouseWheelLeft();
mouseWheelRight

mouseWheelRight():Void
Simulates mouse wheel right. 

  1. browser.mouseWheelRight();
mouseWheelUp

mouseWheelUp():Void
Simulates mouse wheel up. 

  1. browser.mouseWheelUp();
mouseWheelDown

mouseWheelDown():Void
Simulates mouse wheel down. 

  1. browser.mouseWheelDown();
mouseWheelPageLeft

mouseWheelPageLeft():Void
Simulates mouse wheel "page jump" left 

  1. browser.mouseWheelPageLeft();
mouseWheelPageUp

mouseWheelPageUp():Void
Simulates mouse wheel "page jump" up 

  1. browser.mouseWheelPageUp();
mouseWheelPageDown

mouseWheelPageDown():Void
Simulates mouse wheel "page jump" down 

  1. browser.mouseWheelPageDown();
mouseWheelPageRight

mouseWheelPageRight():Void
Simulates mouse wheel "page jump" right 

  1. browser.mouseWheelPageRight();
getMeta

getMeta(name:String):String
Returns value of given meta tag from current page. 

  1. if (browser.getMeta('viewport') == 'user-scalable=no') return;
reload

reload():Void
Reloads the current page. 

  1. browser.reload();
back

back():Void
Navigate back in history 

  1. browser.back();
forward

forward():Void
Navigate forward 

  1. browser.forward();
historyLength

historyLength():Integer
Returns the amount of entries in history 

  1. if (browser.historyLength() != 1) return;
focusNext

focusNext():Void
Set the focus on the next element (tab order) 

  1. browser.focusNext();
focusPrev

focusPrev():Void
Set the focus on the prev element (tab order) 

  1. browser.focusPrev();
stop

stop():Void
Stops the current page from loading. 

  1. browser.stop();
lastUrl

lastUrl():String
Returns a string with the last URL visited (from history) 

  1. browser.lastUrl();
nextUrl

nextUrl():String
If exists - the next url in history is returned 

  1. if (browser.nextUrl()) browser.forward();
invalidate

invalidate():Void
Redraws the browser page 

  1. browser.invalidate();
setUserAgent

setUserAgent(userAgent:String):Void
Sets the User Agent. 

  1. browser.setUserAgent('Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:2.0) Gecko/20100101 Firefox/4.0');
getWidth

getWidth():Integer
Returns the width of the browser. 

  1. browserWidth = browser.getWidth();
getHeight

getHeight():Integer
returns the height of the browser 

  1. browserHeight = browser.getHeight();
shutdown

shutdown():Void
exits the browser (closes the app if used within an html app) 

  1. browser.shutdown();


playerState

Variables

canSeek

canSeek:Boolean
Enable seek. 

  1. playerState.canSeek = true;
canPause

canPause:Boolean
Enable pause/play. 

  1. playerState.canPause = true;
isPaused

isPaused:Boolean
Tells the Boxee OSD the current player state (player can be paused in mouse mode. in that case - this is the only way for boxee to know about it) 

  1. playerState.isPaused = false;
canSetFullScreen

canSetFullScreen:Boolean
Show the 'one-click' fullscreen button on the OSD. When this button is clicked, boxee will attempt to auto choose the correct video. 

  1. playerState.canSetFullScreen = true;
time

time:Float
The time in seconds that has elapsed. 

  1. playerState.time = 135.45;
duration

duration:Float
Specify the length of the video. in seconds. 

  1. playerState.duration = 1485;
progress

progress:Integer
This is automatically computed if both time and duration are specified. If not this sets the percentage of the video that has been completed. 

  1. playerState.progress = 50;
Retrieved from "http://developer.boxee.tv/JavaScript_API"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox