OpenAjax Metadata

OpenAjax Metadata

Home > Widget-Libraries > Widget-Metadata > OpenAjax Metadata

Widget libraries will generally have a layout such as this:

WebContent
|--- library
|    +--- widget.js
+--- metadata
     |--- library
     |    +--- widget_oam.json
     |--- packages.json
     +--- widgets.json

OpenAjax Metadata

The OpenAjax Alliance has crafted a specification which allows us to define a widget. In particular, it can be used to define the widget's contents, as well as required resources (JS, CSS, etc) which must be added to the page for the widget to function properly.

The OpenAjax Metadata (OAM) spec is available here: http://openajax.org/member/wiki/OpenAjax_Metadata_1.0_Specification_Widget_Metadata

While we make use of several of the OAM elements, we are primarily concerned with:

• require - The required resources necessary for the widget to function, such as JS and CSS files.
• property - The properties for this widget, which can be edited in order to affect the funcationality/presentation of the widget.
• content - The default content which gets added to the page.

JSON Format

While the OAM spec is written for XML files, for use with Maqetta we use a JSON variant. In the widget layout at top, this is denoted by the widget_oam.json file.

If you are writing a new OAM.JSON file, it is best to do so in JSON. However, if you are following the OAM spec and have created an XML file, you can generate the corresponding JSON file using the utils/oamXml2Json.js script (require Node.js to run):

node oamXml2Json widget_oam.xml > widget_oam.json

File Location

The heirarchy of OAM files should mirror that of the widget code files themselves, but within the metadata directory.

As you can see in the library layout at top, there exists a widget file at library/widget.js. Given that, the OAM file would reside in metadata/library/widget_oam.json.

As a concrete example, the code file for the dijit/form/Button widget can be found at dijit/form/Button.js. The corresponding OAM file can be found in metadata/dijit/form/Button_oam.json.

AMD Spec Addition

While we keep to the OAM spec, we did make one addition which we felt was necessary: we added support for AMD modules.

For <require> elements, the OAM spec allows a type of "javascript", where the "src" points to (relative path) JavaScript file. But this doesn't work well for AMD modules, which have now been adopted by Dojo, jQuery and many others.

To support AMD, in Maqetta we also support the <require> type of "javascript-module". Since there are several different specifications which could fall under "JavaScript Module", we also added a format property, which can take the value of "amd".

You can see this new type in action in the example below.

Example

Here is the OAM file for "dijit/form/Button":

{
    "id": "http://dojotoolkit.org/dijit/form/Button",
    "name": "dijit.form.Button",
    "spec": "1.0",
    "version": "1.0",
    "require": [
        {
            "type": "javascript-module",
            "format": "amd",
            "src": "dijit/form/Button",
            "$library": "dojo"
        }
    ],
    "library": {
        "dojo": {
            "src": "../../../dojo/dojo.js"
        }
    },
    "property": {
        "type": {
            "datatype": "string",
            "option": [
                {
                    "value": "button"
                },
                {
                    "value": "submit"
                },
                {
                    "value": "reset"
                }
            ],
            "defaultValue": "button",
            "title": "Type"
        },
        "name": {
            "datatype": "string",
            "title": "Name"
        },
        "alt": {
            "datatype": "string",
            "hidden": true
        },
        "value": {
            "datatype": "string",
            "title": "Value"
        },
        "tabIndex": {
            "datatype": "string",
            "defaultValue": "0",
            "title": "Tab Index"
        },
        "disabled": {
            "datatype": "boolean",
            "title": "Disabled"
        },
        "readOnly": {
            "datatype": "boolean",
            "hidden": true
        },
        "intermediateChanges": {
            "datatype": "boolean",
            "hidden": true
        },
        "label": {
            "datatype": "string",
            "title": "Label"
        },
        "showLabel": {
            "datatype": "boolean",
            "defaultValue": true,
            "title": "Show Label"
        },
        "iconClass": {
            "datatype": "string",
            "title": "Icon Class"
        },
        "scrollOnFocus": {
            "datatype": "boolean",
            "description": "On focus, should this widget scroll into view?",
            "hidden": false,
            "defaultValue": true
        }
    },
    "content": "<input type='button'></input>"
}