View source for DevelopWDTVExtPlugin

{| align="right"
 | __TOC__
 |}

= Develop - WDTVExt Plugins =
<b style="color:red">WDTVExt is not available for firmware versions higher than 1.02.21!</b><br>
WDTVExt allow to add custom plugins/extensions to WDlxTV 1.02.21 firmware.<br>
These plugins are written in [https://developer.mozilla.org/en/JavaScript/Guide JavaScript].


== Filename ==
To load your plugin, the filename of your plugin needs to end with '''.plugin.js'''.


== 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 [https://developer.mozilla.org/en/SpiderMonkey/File_object]
** read and write files (can also be used to execute shell commands and retrieve the output)
* XML [https://developer.mozilla.org/En/E4X/Processing_XML_with_E4X]
** 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:
<pre>
// 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.Example: End loading Example plugin");
</pre>
All occurances of '''ExamplePlugin''' are of course to be substituted with the name of your plugin.

=== Page Control ===

==== Global Page Methods ====

===== Page.Top.getParam() / Page.Top.setParam() =====
This can be used in any function you create to read or write @@variables. The @@variables are referenced '''without''' @@!

<pre>
Page.Top.setParam("exampleVariable", "Hello World!")
var exampleVariable = Page.Top.getParam("exampleVariable")
</pre>

===== Page.redraw() =====
Call this with argument '''true''' to force a page redraw:
<pre>
Page.redraw(true)
</pre>

==== 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).
<pre>
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>;
    }
}
</pre>

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.
<pre>
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.Top.setParam("exampleText", page.markupFileName)

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

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.

<pre>
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.Top.setParam("exampleText", "")

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

==== 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.
<pre>
ExamplePlugin.prototype.onPageKey = 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.Top.setParam("exampleKey", key)

        // set @@exampleText to markup file name
        Page.Top.setParam("exampleText", page.markupFileName)

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


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

<pre>
ExamplePlugin.prototype.onPageTimer = function(page) {
    // return if there's no page, important or may cause crashes when omitted !!
    if (!page) { return; }
    // 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
            //

        }
    }
}
</pre>

=== Menu Control ===

On for the menus. Here I will show you how to create new menu items and manipulate existing ones. First we will link the '''Video''' mainmenu item directly to it's childs ('''Local Drives''') child '''Folders'''. So on entering Video on main menu will bring up the movie brower instantly. (Note: you won't be able to access all other items under '''Video''' then, like youtube, mediaservers, etc...)


==== doBuildMenus ====

All the magic of creating new menu items happens in this function. So let's start with this.
The existing menu items are accessed by the '''title''' in this example.
<pre>
ExamplePlugin.prototype.doBuildMenus = function() {
        // we access existing menu items by their names
        Menu.Top["$$Video"].handler = function(){
                Menu.Top["$$Video"]["$$Local Drives"]["$$Folders"].handler()
        };
        Menu.Top["$$Video"].title = "Movies";
        Menu.Top["$$Video"].image = Menu.Top["$$Video"]["$$Local Drives"]["$$Folders"].image
        Menu.Top["$$Video"].focusedImage = Menu.Top["$$Video"]["$$Local Drives"]["$$Folders"].focusedImage
}
</pre>

===== Menu.Top =====

Globaly access menu item properties. These are accessed as shown in the the above example code. To find out the right title (they are case sensitive!), it's useful to write a some logging/displaying code as i've shown with the markup file name in the page section (using '''onMenuSelect()''').

===== new Menu() =====

Let's create a new menu item now. This is going to be a quite simple reboot option.
All the following code should also go into the existing '''doBuildMenus'''.
It's gonna have the same icon image as the config item for now, you can change that.(3rd and 4th parameter in '''new Menu()''')
<pre>
var topMenu = new Menu("Reboot", "$$Reboot", Menu.Top.$$Settings.image, Menu.Top.$$Settings.focusedImage, true)
</pre>

the parameters are '''Menu( name, title, image, focusedImage, visible)'''.

===== addChild() =====

Now we add a submenu item to which will actually reboot the wdtv when selected.
<pre>
topMenu.addChild(new Menu("doReboot", "$$Reboot now", Menu.Top.$$Settings.image, Menu.Top.$$Settings.focusedImage, true))
</pre>

So we have a new Menu created, let's add it to the main menu...
<pre>
Menu.Top.addChild(topMenu)
</pre>
...and add the actual reboot function.
<pre>
Menu.Top.Reboot.doReboot.handler = function() {
	system("sync && reboot")
}
</pre>


==== onMenuSelect ====


==== onMenuDeselect ====


== Repository ==
If you want to maintain your plugin in the WDTVExt web repository, you MUST supply some meta-info inside your script.

 /*
 # meta-name="OSD Notice"
 # meta-desc="Plugin to display short OSD notices"
 # meta-author="recliq"
 # meta-date="2011-07-18"
 # meta-version="1.0.0"
 # meta-type="wdtvext"
 # meta-url="http://forum.wdlxtv.com"
 # meta-filename="OSDNotice.plugin.js"
 */

== Reference ==

=== Menu Variables ===
* 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

=== Menu Events ===
<code>YourPlugin.prototype.doBuildMenus = function() { }</code>

<code>YourPlugin.prototype.onMenuSelect =  function(menuItem){ }</code>

<code>YourPlugin.prototype.onMenuDeselect = function(menuItem) { }</code>


=== Menu Functions ===
 var myMenu = new Menu(name, title, image, focusedImage, visible);

 addChild(childMenu)


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

=== Page Events ===
<code>YourPlugin.prototype.onPageCreated =  function(page){ }</code>

<code>YourPlugin.prototype.onPageEnter =  function(page){ }</code>

<code>YourPlugin.prototype.onPageKey =  function(page, key){ }</code>

<code>YourPlugin.prototype.onPageLeave =  function(page){ }</code>

<code>YourPlugin.prototype.onPageTimer =  function(page){ }</code>


=== Page Functions ===
<code>Page.Top.redraw(true)</code>

<code>Page.Top.getParam("VARIABLE")</code>

<code>Page.Top.setParam("VARIABLE", value)</code>


-- recliq 2010/05/23 --