Builder

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

options

(Object) The configuration options for the builder. See Options below for more information.

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

Return Value

Object

The builder object. See Builder Structure below for more information.

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:

It combines any schemas it finds in the fluid.prefs.schemas namespace;
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:

Name	Type	Description

Name	Type	Description
`options.assembledPrefsEditorGrade`	String	Grade name of the constructed preferences editor; Can be used to instantiate the preferences editor, enhancer and settings store using `fluid.invokeGlobalFunction`.
`options.assembledUIEGrade`	String	Grade name of the constructed enhancer; Can be used to instantiate the enhancer and settings store using `fluid.invokeGlobalFunction`.

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");

This documentation is currently being moved to our new documentation site.

Please view or edit the documentation there, instead.