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

Please view or edit the documentation there, instead.

If you're looking for Fluid Project coordination, design, communication, etc, try the Fluid Project Wiki.

Skip to end of metadata
Go to start of metadata

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

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

Options

NameDescriptionValuesDefault
gradeNames

(Optional) A list of grade names to be used for the builder.

This option can be used to specify the names of grades that define schemas, as an alternative to specifying the schemas through the direct options. If you do not provide the auxiliarySchema option, you must include the grade name of a grade that includes an auxiliary schema.

Array of stringsnone
primarySchema(Optional) A JavaScript object providing primary schema details. See Processing the Schemas below for more details.Object

{}

auxiliarySchema(Optional) A JavaScript object providing auxiliary schema details. See Processing the Schemas below for more details. If you do not specify the grade name of a grade that includes an auxiliary schema, you must include this option.Object

{}

NOTE: You must provide at least one of

  • the auxiliarySchema option, or
  • gradeName indicating an auxiliary schema.

If you provide both, they will be merged (with the auxiliarySchema overriding anything in the grade schema), but you must provide at least one.

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:

NameTypeDescription
options.assembledPrefsEditorGradeStringGrade name of the constructed preferences editor; Can be used to instantiate the preferences editor, enhancer and settings store using fluid.invokeGlobalFunction.
options.assembledUIEGradeStringGrade 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");
  • No labels