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:

• String, integer, or other fundamental JavaScript type. Such a value will be used as is. (E.g., the "OK" string above will not receive any further processing.) Setting a control's content() property to a string representing HTML will typically place the correspoding HTML elements into the DOM.
• An array of Control JSON objects. Each item in the array will be processed in turn.
• A Control JSON object starting with an "html:" key. This will result in the creation of a plain jQuery object.
• A Control JSON object starting with a "control:" key. This will create an instance of a QuickUI control of the designated class.

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

Creating jQuery objects with the "html:" key

$( "<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:

• The Control JSON doesn't allow for fancy coding tricks or idioms. Such techniques can result in compact, efficient code, but at a loss of legibility. Reading someone else's jQuery code can be challenging; there's a good chance they will populate the DOM by some means other than what you yourself would have written. Control JSON, in contrast, requires you to create a UI declaratively, with static data. In the long run, this approach tends to produce UI code which is easier to read and maintain.
• The Control JSON directly reflects the structure of the DOM it will create. With old-school HTML, it's easy to visualize the structure of the DOM the markup will produce at runtime. Similarly, the hierarchical nature of JSON makes it easy to visualize the resulting UI.
• Control JSON is more parsable and tool-able than arbitrary JavaScript. This enables the creation of design-time and compile-time tools that can generate or transform UI 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.