Skip to content

widgets.json spec

Jump to bottom Edit New page
Javier Pedemonte edited this page Jul 9, 2012 · 9 revisions

widgets.json Specification

Home > Widget-Libraries > Widget-Metadata > widgets.json Specification

About

The widget library file widgets.json provides a description of the library and the widgets it contains.

Widget libraries will generally have a layout such as this:

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

Top Level Properties

categories - A set of named properties which represent categories for the library's widgets. See "categories" Property section below.

widgets - An array of widget descriptors. See "widgets Property" section below.

callbacks - Library-level callbacks which enable additional functionality for all widgets in the library. See Helpers section below.

"categories" Property

XXX TODO

"widgets" Property

An array of widget descriptors. The order of the descriptors determines the order of the widgets within each category in Maqetta's Widgets Palette.

name - Name of widget.

description - [optional] A description of the widget. Defaults to name.

type - A unique identifier (i.e. "dijit.form.Button").

category - Name of category under which this widget will be displayed. The given name must match one of the properties under the top-level categories property.

class - [optional] A name which can be used to group a set of widgets. The class name can be used in allowedChild and allowedParent.

icon - [optional] URI, relative to widgets.json file, of an icon which can be used when displaying this widget in Maqetta's Widgets view.

iconBase64 - [optional] Like icon, but represented as a data URI. Generally, it is better to use this property over icon, since it cuts down on network requests.

isLayered - [optional] XXX TODO

resizable - [optional] Specifies if the widget is resizable and in which dimension(s). Allowed values are "none", "width", "height" or "both" (default).

invisible - [optional] XXX TODO

hidden - [optional] If true, the widget will not be displayed in Maqetta's Widgets view; defaults to false. Sometimes it is necessary to create metadata for a widget that will only be used in conjunction with another widget (for example, as a child), but which itself shouldn't be selectable by a Maqetta user.

properties - [optional] XXX TODO

children - [optional] XXX TODO

data - [optional] XXX TODO

metadata - [optional] Override or add to some of the values from a widget's OAM. See the Metadata Override section below.

allowedParent [optional]
allowedChild [optional]

allowedParent ::= "ANY" | { <widget_category> | <widget_type> }+
allowedChild ::= "ANY" | "NONE" | { <widget_category> | <widget_type> }+

where,

  • "ANY" or "NONE" must be by themselves as the value.
  • If empty or not specified,
    • allowedParent defaults to "ANY"
    • allowedChild defaults to "NONE"
  • If neither "ANY" or "NONE", can be any combination of <widget_category> or <widget_type>.
  • <widget_category> is a single word, camel-cased (i.e. "DijitWidgets") representing a set of widget types. Matches a value for the class property in widgets.json.
  • <widget_type> is period-separated words (i.e. "dojo.form.Button"). Matches a value for the type property in widgets.json.

inlineEdit - [optional] See Smart Input section below.

tool - [optional] Specify a custom create tool for this widget. See Helpers section below.

helper - [optional] Provides additional widget info, which cannot be specified by metadata alone. See Helpers section below.

refreshParentOnPropChange - [optional] If true, Maqetta will refresh the parent widget (cause it to be redrawn) when any properties on the child widget are modified.

initialSize - [optional] Used by Maqetta to set the size of a widget when it's first created.

The initialSize attribute only comes into play when the there is:

  • no user specified height/width (e.g., the user didn't drag out region for size)
  • no value returned from the initialSize function in the widget's helper class
initialSize ::= "auto" | <size> | {"flow": "auto" | <size>, "absolute": "auto" | <size>}

where,

  • "auto" must be by itself as the value and indicates to Maqetta to use the following algorithm to determine the initial size of the widget:
  • if added to canvas using "flow" layout
    • if added to html.body:
      • if only child, then {width: 100%, height: auto}
      • else if more than one child, then {width: 100%, height: auto}
    • else if added to container like ContentPane, div, etc. * if only child, then {width: 100%, height 100%} * else if more than one child, then {width: 100%, height: auto}
  • else if added to canvas using "absolute" layout, then {width: 300px, height: 300px}
  • If not specified,
    • Maqetta will only pay attention to user-specified size or helper-specified size
  • <size> is:
    • JSON structure of the form: {"width": <standard css width value>, "height": <standard css height value>}
    • can be specified individually for "flow" and "absolute" layout modes

Proposed Additions

These properties have been discussed as possible additions to the "widgets" object. Maqetta does not currently support these and, as such, adding them will have no effect.

propWhitelist - Subset of property names listed in the widget metadata which will be displayed in the Property view's "Widget-specific" area. Any property not listed is ignored. Comma-separated list.

propBlacklist - Properties not to display in Property view's "Widget-specific" area. Any property listed in widget metadata but not in this list will be displayed. Comma-specific list.

Smart Input (Inline Edit)

Declarative Implementation

The declarative implementation of Smart Input is available to all widgets. You can specify the following properties on the widget descriptor:

"inlineEdit": {
    "property": "title",
    "displayOnCreate": true,
    "multiLine": false
    "supportsHTML": true,
    "helpText": "Some help text here."
}

where,

property: {string} The DOM attribute to update.

displayOnCreate: {boolean} [optional] If true (default), will automatically open the inline editor when widget is added to page.

multiLine: {boolean} [optional] If true, tells inline editor that content may have multiple lines. Defaults to false.

supportsHTML: {boolean} [optional] If true, the text entered by the user is parsed as HTML. Defaults to false.

helpText: {string} [optional] Help text that can be displayed in the inline editor.

disableEncode: XXX TODO

useParent: XXX TODO

Programmatic Implementation

For more control, you can specify your own object extending davinci/ve/input/SmartInput.js. The value of inlineEdit must be an AMD module path, which is relative to widgets.json. For example,

"inlineEdit": "./dijit/layout/BorderContainerInput"

XXX more content here??

Helpers

See Library Helpers.

Metadata Override

By setting the metadata property on a widget's descriptor, we can override or add to the widget's OAM object.

Maqetta supports some additional properties on a widget's property:

refreshFromSource - When a user changes a property on a widget, Maqetta will recreate the widget on the page, specifying the new property value. If the user changes a property for which refreshFromSource is true, then Maqetta will instead refresh the entire page. This is necessary in rare cases where the changed property may, for example, affect how the widget's parent handles the widget (the child).

mustHaveAncestor - Array of widget types (strings). If set, only enable the property if one of the widget's ancestors matches one of the widget types in the array.

dropdownQueryValues
dropdownQueryAttribute - XXX TODO

Add a custom footer
Add a custom sidebar
Clone this wiki locally