The Control JSON format is used by control classes to define values they wish to set on parent classes when rendering new control instances. Control JSON is effectively a JavaScript analogue to HTML markup — both allow you to declaratively define the content of a user interface.

Control JSON is used to process the "inherited" member set on a class' prototype. This is typically set by passing an object with an "inherited:" key to a call to Control.sub().

For example, the following code defines a new subclass of the BasicButton class:

var OKButton = BasicButton.sub({
    className: "OKButton",
    inherited: {
        content: "OK"        
    }
});

The values passed to sub() will be copied to the new class' prototype. In this case, the name "OKButton" will be set as the className on the prototype. The static "inherited" value is likewise copied to the prototype. That sub-object will be processed as Control JSON using the rules defined here.

Control JSON keys invoke control property setters

All keys at the top level of a Control JSON object are interpreted as the names of control properties. The values corresponding to these keys will be passed to the corresponding property setters. This system allows you define the default values which your new class will assign to control instances it creates.

For example, using the OkButton class definition above, the content() property for a new OkButton instance will be set, by default, to the string "OK".

var button = OkButton.create();
var s = button.content(); // returns "OK"

Default values defined in Control JSON are actually set by invoking property setters on the base class. The above definition for OKButton sets the default value by calling the content() property defined by its base class BasicButton. This allows a class to set its own default content, while simultaneously allowing the class to define a custom content() property whose definition overrides its base class' implementation. For an example of how that might work, see the tutorial exercise on Defining your control's content property.

Control JSON value types

The values in a Control JSON object can take one of the following forms:

The latter two value types are described in more detail below.

Creating jQuery objects with the "html:" key

Suppose that you are creating a control, and somewhere within it you want to create a div using the following jQuery code:

$( "<div/> ")
    .height( "250px" )
    .width( "300px" );

The above procedural JavaScript can be represented declaratively as data in Control JSON as follows:

{
    html: "div",
    height: "250px",
    width: "300px"
}

The first "html:" key indicates that you want to create a new jQuery object using the specified HTML. (In normal jQuery, a single tag like "div" selects divs, rather than creating a div; the longer "<div>" is required. As a convenience, Control JSON permits the use of the shorter "div".) The "height:" and "width:" keys which follow indicate that you want to apply the height() and width() setters as a chain.

Creating QuickUI control instances with the "control:" key

Similarly, a "control:" key can be used to instantiate QuickUI controls:

{
    control: Collapsible,
    heading: "Today's photo",
    content: {
        control: FlickrInterestingPhoto,
        photoSize: "m"
    }
}

This JSON creates a FlickrInterestingPhoto control nested within a Collapsible control. It also sets the Collapsible's heading() property, and the photo's photoSize() property.

Setting the "ref:" key on DOM elements and controls

If a Control JSON object starting with "html:" or "control:" also contains an "ref:" key, the resulting element or control will have the indicated string value applied as a CSS class. As a secondary effect, the control class being defined (not the control instance being created) will have an element reference function generated for it. This function will permit quick access to the indicated element at runtime.

See Using functions to reference elements within a control for more discussion and an interactive example.

Advantages of using Control JSON to define a control's appearance

The data-driven approach to using JSON to generate UI arguably has advantages over the equivalent procedural JavaScript code:


To experiment with the Control JSON format, try one of the Tutorial pages, such as the one which covers how to create a control class.