Joost™ Open Distribution Archive (JODA)

This document covers the packaging and distribution system used by Joost Widgets.

Any and all use of the Joost API is subject to the Joost API Terms of Use

The API may change and although we will try and keep these changes to a minimum, some API calls may be deprecated in the future.

Table of Contents

• 1. Overview
• 2. Packaging
• 3. Manifest (install.xml)
• 4. Manifest (config.xml)
• 5. References

1. Overview

Joost Widgets can be built using any number of different logical files, containing XML (largely XHTML and SVG), Javascript, CSS, images, and other such resources. Naturally, while this is a common and well-understood development model very similar to Web application programming, it is inconvenient to distribute multiple files at once.

The solution to that is a simple packaging approach, the Joost Open Distribution Archive (JODA). It is basically a simple Zip archive with a manifest; in other words an approach comparable to that taken by JAR archives, Opera Widgets, or Firefox Extensions.

The intent is for this format to evolve into using digital signing in a way that may not be backwards compatible with the current format, despite the fact that the basic elements described here will naturally persist.

As of Joost version 1.0.3 we support config.xml as well as install.xml, and supports files with the suffix .zip as well as .joda files. More details are below.

2. Packaging

The format of the file packaging is Zip archiving [ZIP]. The version supported in the Joost platform is the same as that supported in recent versions of Gecko. In general all the usual Zip archivers should produce packages compatible with Gecko.

Joost supports two layouts for the content of the archive: either the archive is the root of the widget tree in which case the install.xml or config.xml must be placed there, or the archive contains a single directory which is then the root and contains install.xml or config.xml.

Note that the Joost platform will currently use the first install.xml that it finds as it unpacks the Zip, and consider the path to it inside the archive to be the root. It is therefore recommended to only have only one install.xml or config.xml in the entire archive. This behaviour however is subject to change and should not be relied upon.

The rest of the resources can be placed anywhere inside the root (i.e. at the same level or deeper than where the install.xml or config.xml file is) and have any name.

3. Manifest (install.xml)

The required manifest file install.xml is a very simple and straightforward XML document. An typical example is presented below:

<widget-manifest xmlns='http://joost.com/ns/widget-manifest#'>
  <id>http://widgetarians.org/ids/widgets/dahut/</id>
  <name>The Dahut Widget</name>
  <website>http://widgetarians.org/widgets/dahut/</website>
  <main-file>content/dahut.xml</main-file>
  <icon>content/dahut.png</icon>
</widget-manifest>

Going through the example shows just how simple a format it is. First and foremost, all the elements present above are required except for icon, which is optional (but then you won't have an icon visible for your widget). All the elements must be in the http://joost.com/ns/widget-manifest# namespace. Their exact order does not matter.

Elements in other namespaces can be added anywhere, but elements in the same namespace not listed in this section are forbidden. Likewise, attributes in a namespace are allowed on all of these elements, but attributes in the null namespace are forbidden. Furthermore, while elements in foreign namespaces can be added as children of any manifest element, they are forbidden from having textual content.

Let us look at these elements in further detail:

widget-manifest

This element must be the root element of the manifest. It contains all the others.

id

This is the identifier for the widget. Its form is that of a URI so that it can be easily guaranteed to be unique in the Web at large. The domain part of the address should be a domain that you have control over (but it doesn't have to if you're sure that you can guarantee its uniqueness). Please note that this used to be any string and not specifically a URI. As such, in order to maintain backwards compatibility, we will continue to accept arbitrary strings for several releases. It is however best to switch to using URIs as soon as possible.

name

The name of the widget, which can be any string. Note though that if it's too long the name may get truncated when displayed in the Joost user interface.

website

A link to a page about the widget.

main-file

A path, relative to the root of the widget in the JODA package, pointing to the primary XML document that is to be used as the entry point when the widget is loaded into the Joost platform. That document must be an XML document. Note that in the example we have placed it in a content subdirectory, but there is no requirement to do so.

icon

A path, relative to the root of the widget in the JODA package, pointing to an icon that will represent the widget inside the Joost platform. Supported formats include SVG, PNG, JPEG, GIF, as well as any other format that Gecko supports; it is recommended however that SVG or PNG be used as they are better formats for this purpose. Note that in the example we have placed it in a content subdirectory, but there is no requirement to do so.

4. Manifest (config.xml)

As of Joost version 1.0.3 we support config.xml as well as install.xml. The basic elements within the file are mostly the same as in install.xml, but config.xml is slightly more flexible and has a default for the main-file element. This means you can have very small config files, for example:

<widget-manifest>
  <id>http://widgetarians.org/ids/widgets/dahut/</id>
  <name>The Dahut Widget</name>
  <website>http://widgetarians.org/widgets/dahut/</website>
  <main-file>content/dahut.html</main-file>
  <icon>content/dahut.png</icon>
  <height>500</height>
  <width>400</width>
</widget-manifest>

These elements must be in the http://joost.com/ns/widget-manifest# namespace. Their exact order does not matter.

In further detail:

widget-manifest

As install.xml but there's no need for the namespace to be declared.

id

As install.xml

name

As install.xml

website

As install.xml

main-file

Optional. A path, relative to the root of the widget in the JODA package, pointing to the primary XML or HTML document that is to be used as the entry point when the widget is loaded into the Joost platform. The document can be an HTML document or an XML document, and if not explicitly defined, must be index.html.

icon

Optional. As install.xml

height

Optional. The height of the widget in pixels. Since JWL is being deprecated this replaces a similar attribute of jwl:window. Without it, Joost first looks for jwl:window attributes and then uses sensible defaults.

width

Optional. The width of the widget in pixels. Since JWL is being deprecated this replaces a similar attribute of jwl:window. Without it, Joost first looks for jwl:window attributes and then uses sensible defaults.

5. References

ZIP

ZIP File Format Specification, (PKWare Inc.).