Tutorial 1: Simple "Hello World" widget

This is a tutorial on the basics of writing widgets. It starts with a very basic static widget ("Hello World"), before we move on to more advanced examples that use XMLHttpRequest and the Joost engine.

Requirements

  • Knowledge:
    • Javascript (knowledge of XMLHttpRequest a plus)
    • HTML and CSS (SVG and XML in general a plus)
    • DOM
  • Tools:
    • Text editor
    • Zipping utility
    • Joost (of course!)

You can of course use more tooling if such is your style (raster and SVG editors, TCP monitors, coffee...).

Setting up Joost

Download the latest Joost release and install it (uninstall previous version if you need to, your user preferences will be kept).

Go to 'My Joost', click on the Widgets Menu and select the Widget Manager. From here you can load Joost widgets from your computer, using the 'add widget' button.

install.xml, the manifest

install.xml is the first file Joost will read when it installs your widget. That file provides fundamental information as to how your widget will be loaded, in addition to some useful metadata.

It is a very simple XML document which should look like the following:

<widget-manifest xmlns='http://joost.com/ns/widget-manifest#'>
  <id>http://wor.ld/hello/</id>
  <website>http://wor.ld</website>
  <name>Hello World</name>
  <main-file>hello.xml</main-file>
  <icon>icon.png</icon>
</widget-manifest>
  • id is a simple, easily memorised identifier for your widget, which Joost uses for a variety of purposes internally. It must be a URI, preferably one under your control though just as for namespaces you don't need to have a resource at that address.
  • website is your widget's homepage, somewhere where a user could find additional documentation and help.
  • name is the name that will appear in the widget menu.
  • main-file links to your widget's main file, the document that will be loaded when the user launches your widget.
  • icon is an image (SVG, PNG, JPEG, or if you must GIF) representing your widget (it will be shown in the widget menu). The recommended size is 150 x 150 pixels.

The main file : hello.xml and loading your widget

A basic widget is no different from your typical Web page: it's an XML document, or more precisely an XHTML document with other XML vocabularies such as SVG mixed in. You can also use a vocabulary specific to Joost, the Joost Widgets Language, or JWL (pronounced "jewel").

The main file must be that XHTML document, and its xhtml:head element must contain a jwl:window with a variety of options. The xhtml:title element will be used as the title of the widget.

A very minimalistic hello.xml document is shown below:

<html xmlns='http://www.w3.org/1999/xhtml' xmlns:jwl='http://joost.com/ns/jewel#'>
  <head>
    <title>Hello World!</title>
    <jwl:window width='300px' height='100px' align='right' pinbutton='visible'
                autohide='false'/>
  </head>
</html>
  • autohide will cause the background of your widget to disappear on mouseout or not (possible values: true or false).
  • width and height define the widget window's default size.
  • align defines the window's default position on screen.
  • pinbutton makes the pin button appear or not. That button enables the user to lock the widget so that you can go back to the main screen and still see your widget.

Now that you've written this minimalistic widget you will probably want to see it.

To use a widget for the first time you need to put all the files in a single Zip file and change its extension to joda. Typically, on the command line:

zip -r hello.joda *

On Windows you can use the Windows Zip tool and rename the file manually.

Once you have a JODA archive of your widget ready, fire up Joost, open the widget manager, click on "Add Widget", and select your JODA archive from your file system.

That's it! Your widget is installed and ready to work, go to the widget menu and select it.

Hmm, well, it doesn't do or show much. But that's to be expected, there is nothing in it!

To make the widget show some text, just add a paragraph as you would in an xhtml webpage, e.g:

<html xmlns='http://www.w3.org/1999/xhtml' xmlns:jwl='http://joost.com/ns/jewel#'>
  <head>
    <title>Hello World!</title>
    <jwl:window width='300px' height='100px' align='right' pinbutton='visible'
                autohide='false'/>
  </head>
  <body>
    <p>Hello World!
    </p>
  </body>
</html>

Now re-zip it, uninstall and load it again into Joost, and you should see some text displayed. You can style the text using css and use xhtml elements as usual, including images.

You can download the JODA archive of this example widget here

Troubleshooting

Here are some ways to debug any problems:

  • Try uninstalling and reinstalling your widget, and check the console, using control-shift-D to see if there are any errors there.
  • Check the known issues.
  • Make sure that install.xml exists, has all the right elements and points to the right main-file.
  • Check that all your XML documents are well-formed.
  • If the problem persists, ask on the mailing list

Next Steps

Hopefully you've made your first widget and you now know how to set up Joost and how to begin making a new widget. In the next tutorial you'll learn how to use Javascript in your widget and some JWL forms elements as well as how to use CSS to style your widget.

Start | Next


TV Anywhere, anytime