Revision as of 09:14, 23 May 2010

Develop - WDTV Ext's Plugin

WDTV Ext allow to add custom plugins/extensions to WDlxTV firmware.

All plugins start with Javascript file.

Filename

To load your plugin, the first Javascript filename needs to ends with ".plugin.js".

Event

Menu Event

Variable

• menuitem
  • name - Menu name
  • title - Menu displayed title
  • image - Path to menu displayed icon
  • focusedImage - Path to selected menu icon
  • visible - Visible or not
  • firstChild - first cild item
  • parent - parent item
  • next - next menu item
  • prev - previous menu item
  • childCount - submenu item count

Event

YourPlugin.prototype.doBuildMenus = function() { }

YourPlugin.prototype.onMenuSelect = function(menuItem){ }

YourPlugin.prototype.onMenuDeselect = function(menuItem) { }

Page Event

Variable

• page
  • markupFileName - OSD XML Filename
  • extraContent - XML Content to append the original XML File
  • isMediaListPage
  • selectedMedia
    • name
    • folder
    • path
  • setParam(paramName, value)
  • getParam(paramName)

Event

YourPlugin.prototype.onPageCreated = function(page){ }

YourPlugin.prototype.onPageEnter = function(page){ }

YourPlugin.prototype.onPageKey = function(page, key){ }

YourPlugin.prototype.onPageLeave = function(page){ }

YourPlugin.prototype.onPageTimer = function(page){ }

Getting Started...

I will try to explain here how to start developing WDTVExt plugins. I'm by no means a 'programmer' and learned javascript just recently while discovering WDTVExt. So if I'm doing something wrong here, please correct me!

What can we do with WDTVExt? (v0.23.5)

• File [1]
  • read and write files (can also be used to execute shell commands and retrieve the output)
• XML [2]
  • parse/manipulate XML content
• Curl
  • fetch web content with curl
• Page Control
  • add extra XML content
  • introduce new @@variables to page
  • read all @@variables from page
  • write all @@variables to page
  • force redraw of page
  • react to keys pressed on remote
• Menu Control
  • add new menu items
  • add new submenu item
  • maniplulate menu and submenu items (title, image, focusedImage, handler, ...)

What can't we do with WDTVExt? (v0.23.5)

• create entire custom pages
• create menu items that link to a folder or file
• create setup pages

Now, let's start creating our first WDTVext plugin: Example.plugin.js

Example Plugin

Basic Plugin Skeleton

Every Plugin strats with some basic plugin constructor:

// all traces both trace and traceln will output in /tmp/dmaosd.log (or /tmp/wdtvext.log)
traceln("Plugin.Example: Start loading Example plugin")

function ExamplePlugin(path) {
    this.rootPath = path;
    traceln("Plugin.Example:   base path is " + this.rootPath);
}

// chain ExamplePlugin with proper inheritance - classical in javascript
ExamplePlugin.prototype = new Plugin();
ExamplePlugin.prototype.constructor = ExamplePlugin;

//
// our later to develop code and functions will
//
// go here, left blank for now
//

// create our plugin with baseParg pointing to current script path
// global variables scriptName, scriptLocation and scriptFullPath are available, no need to do the following
ExamplePlugin.instance = new ExamplePlugin(scriptPath);

// register our plugin with WDTVext
Plugin.registerPlugin(ExamplePlugin.instance);

traceln("Plugin.MediaFolder: End loading MediaFolder plugin");

All occurances of ExamplePlugin are of course to be substituted with the name of your plugin.

Page Control

Global Page Methods

Page.getParam() / Page.setParam()

This can be used in any function you create to read or write @@variables. The @@variables are referenced without @@!

Page.setParam("exampleVariable", "Hello World!")
var exampleVariable = Page.getParam("exampleVariable")

Page.redraw()

Call this with argument true to force a page redraw:

Page.redraw(true)

onPageCreated

This is called when a new page is created. This is the place where we add our extra content to display some cool output on the screen. So we are going to add two text lines to the menu page (fill this code into the above at the mentioned space).

ExamplePlugin.prototype.onPageCreated =  function(page){

    // villa_home.xml is the menu page we want our text only to show on this page...
    if(page.markupFileName == "villa_home.xml"){

        // check for existing extraContent 
        if(!page.extraContent) {
            page.extraContent = ""
        }

        // now we add our own extra content...
        page.extraContent += <wrapper>
            <text text="@@exampleText" x="50" y="50" w="768" h="20" textcolor="0xffffff" align="left" fontsize="18"/>
            <text text="@@exampleKey" x="50" y="80" w="768" h="20" textcolor="0xffffff" align="left" fontsize="18"/>
        </wrapper>;
    }
}

This creates two lines of white text in the upper left area of the screen, which will display the contents of the two variables @@exampleText and @@exampleKey. Since we haven't set those variables yet, we see... nothing! ;)

onPageEnter

Ok, having text elements we can't see isn't worth much... let's change that. After the page is created the onPageEnter event is called, we use this to populate some content to our variables.

ExamplePlugin.prototype.onPageEnter = function(page) {

    // again we want this only to execute on main menu...
    if(page.markupFileName == "villa_home.xml"){

        // set @@exampleText to the filename of the current xml page 
        Page.setParam("exampleText", page.markupFileName)

        // sometimes it's needed to redraw the page, we will do this just in case...
        Page.redraw(true)
    }
}

Now we should see villa_home.xml as white text in upper left screen.

onPageLeave

Same as onPageEnter but when page is left. We delete the text again here.

ExamplePlugin.prototype.onPageLeave = function(page) {

    // again we want this only to execute on main menu...
    if(page.markupFileName == "villa_home.xml"){

        // set @@exampleText to the filename of the current xml page 
        Page.setParam("exampleText", "")

        // sometimes it's needed to redraw the page, we will do this just in case...
        Page.redraw(true)
    }
}

onPageKey

Things are starting to get interesting with this event now. This event is called everytime you press a key on the remote (or you use /tmp/ir_injection ;)). Let's add some code to display the last pressed key.

ExamplePlugin.prototype.onPageLeave = function(page, key) {

    // again we want this only to execute on main menu...
    if(page.markupFileName == "villa_home.xml"){

        // set @@exampleKey to key number
        Page.setParam("exampleKey", key)

        // sometimes it's needed to redraw the page, we will do this just in case...
        Page.redraw(true)
    }
}

onPageTimer

The onPageTimer event gets called every ~500ms. You can use this to handle periodic events. If you want your funtion to be executed less often, you have to skip some calls like shown below. It will execute the code every 5th call, so every ~2,5s.

ExamplePlugin.prototype.onPageTimer = function(page) {

    // again we want this only to execute on main menu...
    if(page.markupFileName == "villa_home.xml"){

        if (!this.skipCounter) {
            this.skipCounter = 0
        }

        if (this.skipCounter < 5) {
            this.skipCounter++
        } else {
            this.skipCounter = 0

            //
            // here goes the code that should be executed every 2,5s
            //

        }
    }
}

Menu Control

Global Menu Methods

Menu.Top

new Menu()

addChild()

firstChild()

lastChild()

onMenuSelect

onMenuDeselect

doBuildMenus

-- recliq 2010/05/23 --