Overview

The Infusion Preferences Framework includes a tool called the Builder, which automatically creates all the components you need given primary and auxiliary schemas. The builder constructs all the components necessary to render the preferences editor, store preferences, and respond to changes in preferences. However, you'll generallyl want to use the simpler method "fluid.prefs.create" for creating and instantiating a Preferences Editor.

var builder = fluid.prefs.builder(<options>)

NOTE: In this form, the namespace property of the auxiliary schema is required.

Parameters

where options is a JavaScript object containing information configuring your builder.

Return Value

Options

{}

{}

Usage

The simplest usage of the builder is through the two schema options:

var myBuilder = fluid.prefs.builder({
    primarySchema: {...},
    auxiliarySchema: {...}
});

Using the Starter Preferences

The Preferences Framework includes primary and auxiliary schema for a set of preferences, referred to to as the "starter set." This set includes the following preferences:

• text size
• text font
• line spacing
• colour contrast
• table of contents
• inputs larger
• emphasize links

To use these preferences and the panels that come with them, simply use the Framework-provided starter auxiliary schema grade name, fluid.prefs.auxSchema.starter, as shown below:

var myBuilder = fluid.prefs.builder({
    gradeNames: ["fluid.prefs.auxSchema.starter"]
});

You may need to override the template and message bundle path prefixes, if your relative paths are different than the defaults:

var myBuilder = fluid.prefs.builder({
    gradeNames: ["fluid.prefs.auxSchema.starter"],
    auxiliarySchema: {
        "templatePrefix": "<custom relative path to template folder>",
        "messagePrefix": "<custom relative path to messages folder>"
    }
});

It is not necessary to specify the primary schema; The builder will automatically find the preference specifications provided by the Framework and build a primary schema (see Processing the Schemas below for more information).

Auxiliary Schema Grade

If a grade name is used to provide the auxiliary schema, the grade must meet certain criteria:

• it must have a grade of fluid.prefs.auxSchema, and
• it must have an auxiliarySchema option defined.

fluid.defaults("my.editor.auxSchema", {
    gradeNames: ["fluid.prefs.auxSchema", "autoInit"],
    auxiliarySchema: {
        // auxiliary schema specifics here
    }
});
var myBuilder = fluid.prefs.builder({
    gradeNames: ["my.editor.auxSchema"]
});

Processing the Schemas

The Preferences Framework builds an internal, preliminary primary schema as follows:

1. It combines any schemas it finds in the fluid.prefs.schemas namespace;
2. It merges these with any information found in the primarySchema option.

This preliminary schema is then filtered based on the preferences found in the auxiliary schema to produce the subset of only preferences found in both the primary and auxiliary schemas. This set of preferences will be the final set supported by the builder. NOTE: All panels and enactors defined in the auxiliary schema will be created and rendered, but only those that have corresponding preferences in the primary schema will actually work.

Output of Builder

Builder Object

The builder object returned by a call to fluid.prefs.builder has the following properties that can be used to instantiate the constructed preferences editor:

Functions

The builder also creates free functions that can be used to instantiate the preferences editor and enhancer. These functions are created within the namespace specified in the auxiliary schema, if specified, or in a unique namespace, "fluid.prefs.created_UNIQUE_ID".

The functions created include:

• prefsEditor() which can be used to instantiate the preferences editor, enhancer and settings store
• uie() which can be used to instantiate the enhancer and settings store

Examples

Starter schemas, default namespace

var myBuilder = fluid.prefs.builder({
	// use the Framework-provided starter schema grade
    gradeNames: ["fluid.prefs.auxSchema.starter"],

    // override the paths in the starter grade
    auxiliarySchema: {
        "templatePrefix": "../../../framework/preferences/html/",
        "messagePrefix": "../../../framework/preferences/messages/"
    }

	// by not providing a primarySchema, the 'starter' prefs will be used
});

// instantiate the default 'fat panel' version of the preferences editor
// (along with the enhancer and settings store)
fluid.invokeGlobalFunction(builder.options.assembledPrefsEditorGrade, [".fat-panel-container"]);

// alternatively, the same instantiation can be accomplished using the public function
fluid.prefs.constructed.prefsEditor(".fat-panel-container");

Custom schemas, custom namespace

// define a primary schema, with a single preference
var myPrefsPrimary = {
    "my.prefs.textSize": {
        type: "number",
        "default": 12,
        minimum: 8,
        maximum: 24,
        divisibleBy: 2
    }
};
// define a grade containing the auxiliary schema, specifying
// the panel and enactor for the preference
fluid.defaults("my.prefs.editor.aux", {
    gradeNames: ["fluid.prefs.auxSchema", "autoInit"],
    auxiliarySchema: {
        namespace: "my.prefs.editor",
        templatePrefix: "templates/",
        template: "%prefix/MyEditorTemplate.html",
        messagePrefix: "messages/",
        message: "%prefix/MyEditorStrings.html",
        textSize: {
            type: "my.prefs.textSize",
            enactor: {
                type: "my.prefs.enactors.textSize" // defined elsewhere
            },
            panel: {
                type: "my.prefs.panels.textSize", // defined elsewhere
                container: ".my-text-size",
                template: "%prefix/textSizeTemplate.html",
                message: "%prefix/textSize.json"
            }
        }
    }
});
// create the builder using the auxiliary schema grade and the primary schema object
var myBuilder = fluid.prefs.builder({
    gradeNames: ["my.prefs.editor.aux"],
    primarySchema: myPrefsPrimary
});
// instantiate the editor, enhancer and settings store
my.prefs.editor.prefsEditor(".my-editor-container");