widgets.json spec

widgets.json Specification

Home > JS-Library-API > widgets.json Specification

This is a sub-page of JS-Library-API. Please refer to that page for the Overview and Terminology.

About

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

Top Level Properties

name - A short name descriptor for the library (i.e. "dojo").

longName - A long name descriptor for the library (i.e. "Dojot Toolkit").

version - The library version.

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.

"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 view.

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

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 Inline Edit section below.

tool - [optional] XXX TODO

helper - [optional] See Helpers section below.

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.

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

Inline Edit

Declarative Implementation

The declarative implementation of the Inline Edit function that is available to all widgets. You can specify the following property on the descriptor:

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

where,

property: {string} The DOM attribute to update. XXX default?

displayOnCreate: {boolean} true will open the inline editor when widget is added to page. XXX default?

multiLine: {boolean} true tells inline editor that content may have multiple lines. XXX default?

supportsHTML: {boolean} Set to true if the content can have HTML tags. Default is false.

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

Programmatic Implementation

For more control, you can specify a class name as the value of descriptor.inlineEdit. For example,

"inlineEdit": "davinci.ve.input.BorderContainerInput"

XXX Class name should be in style used by Helpers, i.e. "davinci.libraries.dojo.dijit.layout.BorderContainerHelper"

The class must extend davinci.ve.input.SmartInput.

XXX TODO More content here

Helpers

Maqetta attempts to do the best it can for most widgets, but for some widgets the default action may not be appropriate. Maqetta makes use of helper objects, which contain callbacks which are invoked at the appropriate time.

The helper objects are defined in JS files, the object name is specified as descriptor.helper.

A helper object may declare the following callback functions:

create - Invoked at end of davinci.ve.DijitWidget (not implemented for other widget types). This callback is different than CreateTool objects since in this case, the callback is standalone. In the case of CreateTool, the create() and _create() functions override the default functionality.

checkValue - XXX TODO

destroyWidget - XXX TODO

getContainerNode - If widget is a container (descriptor.isContainer is true), ... (XXX TODO).

getChildrenData - XXX TODO

getData - XXX TODO

getPropertyValue - XXX TODO

popup - XXX TODO

tearDown - XXX TODO