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.

Instantiating the Preferences Editor

This article describes how to instantiate a preferences editor created using the Infusion Preferences Framework. This is part of the Tutorial - Creating a Preferences Editor Using the Preferences Framework.

 

On This Page

 

 

Using a Single Function Call

The simplest way to instantiate the Preferences Editor defined by your schemas is using the convenience function fluid.prefs.create(). This function uses the schemas you specify to build all the necessary components, including the Editor itself, the settings store and the enhancer and enactors. It instantiates and renders the Editor onto the page and returns the editor object.

SeparatedPanel Editor

The default layout for a Preferences Editor is a separated panel, typically rendered at the top of the page and hidden until a user interaction that slides it into view. The following examples show this use, using either the auxiliarySchema property or an auxiliary schema grade:

Example: Instantiation using auxiliary schema property
var myEditor = fluid.prefs.create(".prefs-editor-container", {
    build: {
        primarySchema: myPrimarySchema,
        auxiliarySchema: myAuxiliarySchema
    }
});
Example: Instantiation using auxiliary schema grade
var myEditor = fluid.prefs.create(".prefs-editor-container", {
    build: {
        gradeNames: ["my.auxSchemaGrade"],
        primarySchema: myPrimarySchema
    }
});

 

Full-Page Editor

The Preferences Framework also provides built-in configurations for two full-page modes: with or without a preview. To choose one of these configurations, add a second option, as shown in the example below:

Sample instantiation of a full-page preferences editor with no preview
var myEditor = fluid.prefs.create(".prefs-editor-container", {
    build: {
        primarySchema: myPrimarySchema,
        auxiliaryScham: myAuxiliarySchema
    },
    prefsEditor: {
        prefsEditorType: "fluid.prefs.fullNoPreview"
    }
});
Sample instantiation of a full-page preferences editor with a preview
var myEditor = fluid.prefs.create(".prefs-editor-container", {
    build: {
        primarySchema: myPrimarySchema,
        auxiliaryScham: myAuxiliarySchema
    },
    prefsEditor: {
        prefsEditorType: "fluid.prefs.fullPreview",
        prefsEditor: {
            preview: {
                templateUrl: "html/previewTemplate.html"
            }
        }
    }
});

In this example, the preview.templateUrl options specifies the relative path and filename of an HTML template to use inside the preview iFrame.

 

Using the Builder

You can also instantiate the Preferences Editor using a two-step process:

  1. Use the Builder to build the editor, then
  2. Instantiate the editor built by the builder.

The single function call described in the previous section actually carries out these two steps for you, it just conveniently hides that fact from you. If you are going to be instantiating only the settings store and the page enhancer, then you must use this two-step process, so if you're planning to write a single script that can be shared on pages that do and don't have the preferences editor, you'll want to use this process.

Build the Editor

Build the editor, settings store and enhancer with a call to the Preferences Framework Builder. As with the single function call described above, the Builder can be used with either the auxiliarySchema property or with an auxiliary schema grade.

NOTE: If you're going to use the builder, your auxiliary schema MUST specify a namespace. You'll need this namespace to access the components created by the builder.

Example: Using the builder with the auxiliarySchema property
vary myAuxiliarySchema = {
    namespace: "my.prefs",
    ...
};
fluid.prefs.builder({
    primarySchema: myPrimarySchema,
    auxiliaryScham: myAuxiliarySchema
});
Example: Using the builder with an auxiliary schema grade
fluid.defaults("my.auxSchemaGrade", {
    gradeNames: ["fluid.prefs.auxSchema", "autoInit"],
    auxiliarySchema: {
        namespace: "my.prefs",
        ....
    }
});
fluid.prefs.builder({
    gradeNames: ["my.auxSchemaGrade"],
    primarySchema: myPrimarySchema
});

Instantiate the Editor

Once you've run the builder, you can access the preferences editor through the namespace you specified in your auxiliary schema:

Instantiating the default separated-panel editor
var myEditor = my.prefs.prefsEditor(".prefs-editor-container");
Instantiating a 'full-page with preview' editor
var myEditor = my.prefs.prefsEditor(".prefs-editor-container", {
    prefsEditorType: "fluid.prefs.fullPreview",
    prefsEditor: {
        preview: {
            templateUrl: "html/previewTemplate.html"
        }
    }
});

 

 

Back to Tutorial - Creating a Preferences Editor Using the Preferences Framework

Â