Skip to content

UserInterfaceOptionsAPI.md

Latest commit

 

History

History
802 lines (736 loc) · 21.7 KB

UserInterfaceOptionsAPI.md

File metadata and controls

802 lines (736 loc) · 21.7 KB
Raw
title User Interface Options API
layout default

User Interface Options API

The User Interface Options (UI Options) component allows users to transform the presentation of the user interface and content resources so that they are personalized to the individual user's needs.

UI Options does three things:

  • places a preferences editor dialog with a set of six panels in a collapsible panel at the top of the page, accessible through a button in the upper right corner of the page;
  • instantiates a cookie-based Settings Store for storing the user's preferences; and
  • acts upon the user's preferences.

UI Options is a convenient way to add a simple separated-panel preferences editor to any page. The interface will automatically support the set of "starter" preferences provided by the Preferences Framework, in their default configuration.

Note: If you require any customization of UI Options, you should consider using the Builder tool of the Preferences Framework directly.

Screen shot of the UI Options Component

Creator

Use the following function to create a UI Options component:

Method fluid.uiOptions.prefsEditor(container, options);
Description Instantiate a separated panel version of the UI Options component, which displays the controls in a sliding panel at the top of the page.
Parameters
container
A CSS-based selectors, single-element jQuery object, or DOM element that identifies the root DOM node where the UI Options interface should be placed.
options
An optional data structure that configures the UI Options component, as described below.
Returns The UI Options component
Examples 

var myUIO = fluid.uiOptions.prefsEditor("#myContainer", {
    tocTemplate: "../../components/tableOfContents/html/TableOfContents.html"
});
Notes The UI Options uses the page itself as a live "preview:" As users adjust controls, the page is modified accordingly.

Supported Events

Listeners can be attached to any supported events through a component's listeners option. Values can be a function reference (not a string function name) or an anonymous function definition, as illustrated below:

var myComponent = component.name("#myContainerID", {
    listeners: {
        eventName1: functionName,
        eventName2: function (params) {
            ...
        }
    }
});

For information on the different types of events, see Infusion Event System.

onReady

Description This event fires when the UI Options component is fully instantiated, rendered and ready to use.
Type default
Parameters
uio
The instantiated UI Options component.

onPrefsEditorReady

Description This event fires when the UI Options interface has been rendered into the iframe. 
            <p><em><strong>Note:</strong> use <code>onReady</code> if the listener needs UI Options to be both rendered and ready to use.</em></p>
        </td>
    </tr>
    <tr>
        <th>Type</th>
        <td>default</td>
    </tr>
    <tr>
        <th>Parameters</th>
        <td>
            <dl>
                <dt>prefsEditorLoader</dt>
                <dd>
                    The instantiated preference editor loader component.
                </dd>
            </dl>
        </td>
    </tr>
</tbody>

Options

The second argument to the creator function is the options argument. This is a JavaScript object containing name/value pairs: The name is the name of the option and the value is the desired setting. Components define their own default values for options, but integrators can override these defaults by providing new values using the options argument. For technical information about how options are merged with defaults, see Options Merging.

var uio = fluid.uiOptions.prefsEditor(".myContainer", {
    <option1Name>: <option1value>,
    <option2Name>: <option2value>
    ...
});

The options supported by UI Options are described below.

tocTemplate

Description The tocTemplate option allows you to specify a custom relative path to the templates used by generating table of contents. This template can be found in the source tree of the Infusion distribution.
Default "../../components/tableOfContents/html/TableOfContents.html"
Example 

fluid.uiOptions.prefsEditor("#myContainer", {
    tocTemplate: "html/myTocTemplate.html"
});
See also Table of Contents API

templatePrefix

Description The templatePrefix option allows you to specify a custom relative path to the templates used by the UI Options interface. These templates can be found in the source tree of the Infusion distribution.
Default "../../framework/preferences/html/"
Example 

fluid.uiOptions.prefsEditor("#myContainer", {
    templatePrefix: "../infusion/framework/preferences/html/"
});
See also messagePrefix

messagePrefix

Description The messagePrefix option allows you to specify a custom relative path to the messages used by the UI Options interface. These message files can be found in the source tree of the Infusion distribution.
Default "../../framework/preferences/messages/"
Example 

fluid.uiOptions.prefsEditor("#myContainer", {
    messagePrefix: "../infusion/framework/preferences/messages/"
});
See also templatePrefix

prefsEditor

Description The prefsEditor option allows you to specify a data structure to config the prefsEditor component.
Default null
Example 

fluid.uiOptions.prefsEditor("#myContainer", {
    prefsEditor: {
        listeners: {
            onReady: function (internalEditor) {...}
            onReset: function (internalEditor) {...}
        }
    }
});

prefsEditorType

Description The prefsEditorType option allows you to specify a custom prefsEditorLoader grade component.
Default "fluid.pageEnhancer"
Example 

fluid.uiOptions.prefsEditor("#myContainer", {
    prefsEditorType: "myNamespace.myPrefsEditor"
});

enhancerType

Description The enhancerType option allows you to specify a custom enhancer grade component.
Default "fluid.pageEnhancer"
Example 

fluid.uiOptions.prefsEditor("#myContainer", {
    enhancerType: "myNamespace.myUIEnhancer"
});

storeType

Description The storeType option allows you to specify a custom store grade component.
Default "fluid.globalSettingsStore"
Example 

fluid.uiOptions.fullNoPreview("#myContainer", {
    storeType: "myNamespace.mySettingsStore"
});
See also Cookie Settings Store

Modifiable Preference Defaults

Text Size

Description

To change the text size of the page by a multiplier factor.

            <p>The corresponding starter <a href="PrimarySchemaForPreferencesFramework.md">primary schema</a> component for the "Text Size" preference is <code>fluid.prefs.schemas.textSize</code>. To modify its default information, you can redefine this component before calling the <a href="#creator>Creator</a> <code>fluid.uiOptions.prefsEditor</code>.<p>
        </td>
    </tr>
    <tr>
        <th>Default</th>
        <td>


fluid.defaults("fluid.prefs.schemas.textSize", {
    gradeNames: ["autoInit", "fluid.prefs.schemas"],
    schema: {
        "fluid.prefs.textSize": {
            "type": "number",
            "default": 1,   // The default is the original text size
            "minimum": 1,   // The minimum value allowed
            "maximum": 2,   // The maximum value allowed
            "divisibleBy": 0.1  // The stepper value for the slider
        }
    }
});


        </td>
    </tr>
    <tr>
        <th>Example</th>
        <td>


fluid.defaults("fluid.prefs.schemas.textSize", {
    gradeNames: ["autoInit", "fluid.prefs.schemas"],
    schema: {
        "fluid.prefs.textSize": {
            "type": "number",
            "default": 5,
            "minimum": 1,
            "maximum": 10,
            "divisibleBy": 1
        }
    }
});

fluid.uiOptions.prefsEditor("#myContainer", {
    tocTemplate: "html/myTocTemplate.html"
});


        </td>
    </tr>
</tbody>

Line Space

Description

To change the line space of the page by a multiplier factor.

            <p>The corresponding starter <a href="PrimarySchemaForPreferencesFramework.md">primary schema</a> component for the "Line Space" preference is <code>fluid.prefs.schemas.lineSpace</code>. To modify its default information, you can redefine this component before calling the <a href="#creator">Creator</a> <code>fluid.uiOptions.prefsEditor</code>.<p>
        </td>
    </tr>
    <tr>
        <th>Default</th>
        <td>


fluid.defaults("fluid.prefs.schemas.lineSpace", {
    gradeNames: ["autoInit", "fluid.prefs.schemas"],
    schema: {
        "fluid.prefs.lineSpace": {
            "type": "number",
            "default": 1,   // The default text size is 1, the original line space
            "minimum": 1,   // The minimum value allowed
            "maximum": 2,   // The maximum value allowed
            "divisibleBy": 0.1  // The stepper value for the slider
        }
    }
});


        </td>
    </tr>
    <tr>
        <th>Example</th>
        <td>


fluid.defaults("fluid.prefs.schemas.lineSpace", {
    gradeNames: ["autoInit", "fluid.prefs.schemas"],
    schema: {
        "fluid.prefs.lineSpace": {
            "type": "number",
            "default": 1,
            "minimum": 0.5,
            "maximum": 2.5,
            "divisibleBy": 0.1
        }
    }
});

fluid.uiOptions.prefsEditor("#myContainer", {
    tocTemplate: "html/myTocTemplate.html"
});


        </td>
    </tr>
</tbody>

Text Font

Description

To change the text font of the page.

            <p>The corresponding starter <a href="PrimarySchemaForPreferencesFramework.md">primary schema</a> component for the "Text Font" preference is <code>fluid.prefs.schemas.textFont</code>. To modify its default information, you can redefine this component before calling the <a href="#creator">Creator</a> <code>fluid.uiOptions.prefsEditor</code>.<p>
        </td>
    </tr>
    <tr>
        <th>Default</th>
        <td>


fluid.defaults("fluid.prefs.schemas.textFont", {
    gradeNames: ["autoInit", "fluid.prefs.schemas"],
    schema: {
        "fluid.prefs.textFont": {
            "type": "string",      // The data type
            "default": "default",  // The default is the original font
            "enum": ["default", "times", "comic", "arial", "verdana"]  // The enumeration of possible values
        }
    }
});


        </td>
    </tr>
    <tr>
        <th>Example</th>
        <td>


fluid.defaults("fluid.prefs.schemas.textFont", {
    gradeNames: ["autoInit", "fluid.prefs.schemas"],
    schema: {
        "fluid.prefs.textFont": {
            "type": "string",
            "default": "arial",
            "enum": ["default","comic", "arial"]
        }
    }
});

fluid.uiOptions.prefsEditor("#myContainer", {
    tocTemplate: "html/myTocTemplate.html"
});


        </td>
    </tr>
</tbody>

Contrast

Description

To change the foreground and background of the page.

            <p>The corresponding starter <a href="PrimarySchemaForPreferencesFramework.md">primary schema</a> component for the "Contrast" preference is <code>fluid.prefs.schemas.contrast</code>. To modify its default information, you can redefine this component before calling the <a href="#creator">Creator</a> <code>fluid.uiOptions.prefsEditor</code>.<p>
        </td>
    </tr>
    <tr>
        <th>Default</th>
        <td>


fluid.defaults("fluid.prefs.schemas.contrast", {
    gradeNames: ["autoInit", "fluid.prefs.schemas"],
    schema: {
        "fluid.prefs.contrast": {
            "type": "string",     // The data type
            "default": "default", // The default is the original contrast settings
            "enum": ["default", "bw", "wb", "by", "yb", "lgdg"] // The enumeration of possible values
        }
    }
});


        </td>
    </tr>
    <tr>
        <th>Example</th>
        <td>


fluid.defaults("fluid.prefs.schemas.contrast", {
    gradeNames: ["autoInit", "fluid.prefs.schemas"],
    schema: {
        "fluid.prefs.contrast": {
            "type": "string",
            "default": "bw",
            "enum": ["default", "bw", "wb"]
        }
    }
});

fluid.uiOptions.prefsEditor("#myContainer", {
    tocTemplate: "html/myTocTemplate.html"
});


        </td>
    </tr>
</tbody>

Table of Contents

Description

To create and render a section of "Table of Contents" at the top of the page.

            <p>The corresponding starter <a href="PrimarySchemaForPreferencesFramework.md">primary schema</a> component for the "Table of Contents" preference is <code>fluid.prefs.schemas.tableOfContents</code>. To modify its default information, you can redefine this component before calling the <a href="#creator">Creator</a> <code>fluid.uiOptions.prefsEditor</code>.<p>
        </td>
    </tr>
    <tr>
        <th>Default</th>
        <td>


fluid.defaults("fluid.prefs.schemas.tableOfContents", {
    gradeNames: ["autoInit", "fluid.prefs.schemas"],
    schema: {
        "fluid.prefs.tableOfContents": {
            "type": "boolean",   // The data type
            "default": false     // Not to show table of contents by default
        }
    }
});


        </td>
    </tr>
    <tr>
        <th>Example</th>
        <td>


fluid.defaults("fluid.prefs.schemas.tableOfContents", {
    gradeNames: ["autoInit", "fluid.prefs.schemas"],
    schema: {
        "fluid.prefs.tableOfContents": {
            "type": "boolean",
            "default": true
        }
    }
});

fluid.uiOptions.prefsEditor("#myContainer", {
    tocTemplate: "html/myTocTemplate.html"
});


        </td>
    </tr>
</tbody>

Emphasize Links

Description

To underline and bold links on the page.

            <p>The corresponding starter <a href="PrimarySchemaForPreferencesFramework.md">primary schema</a> component for the "Emphasize Links" preference is <code>fluid.prefs.schemas.emphasizeLinks</code>. To modify its default information, you can redefine this component before calling the <a href="#creator">Creator</a> <code>fluid.uiOptions.prefsEditor</code>.<p>
        </td>
    </tr>
    <tr>
        <th>Default</th>
        <td>


fluid.defaults("fluid.prefs.schemas.emphasizeLinks", {
    gradeNames: ["autoInit", "fluid.prefs.schemas"],
    schema: {
        "fluid.prefs.emphasizeLinks": {
            "type": "boolean",   // The data type
            "default": false     // Not to emphasize links by default
        }
    }
});


        </td>
    </tr>
    <tr>
        <th>Example</th>
        <td>


fluid.defaults("fluid.prefs.schemas.emphasizeLinks", {
    gradeNames: ["autoInit", "fluid.prefs.schemas"],
    schema: {
        "fluid.prefs.emphasizeLinks": {
            "type": "boolean",
            "default": true
        }
    }
});

fluid.uiOptions.prefsEditor("#myContainer", {
    tocTemplate: "html/myTocTemplate.html"
});


        </td>
    </tr>
</tbody>

Inputs Larger

Description

To enlarge input fields on the page.

            <p>The corresponding starter <a href="PrimarySchemaForPreferencesFramework.md">primary schema</a> component for the "Inputs Larger" preference is <code>fluid.prefs.schemas.inputsLarger</code>. To modify its default information, you can redefine this component before calling the <a href="#creator">Creator</a> <code>fluid.uiOptions.prefsEditor</code>.<p>
        </td>
    </tr>
    <tr>
        <th>Default</th>
        <td>


fluid.defaults("fluid.prefs.schemas.inputsLarger", {
    gradeNames: ["autoInit", "fluid.prefs.schemas"],
    schema: {
        "fluid.prefs.inputsLarger": {
            "type": "boolean",   // The data type
            "default": false     // Not to enlarge input fields by default
        }
    }
});


        </td>
    </tr>
    <tr>
        <th>Example</th>
        <td>


fluid.defaults("fluid.prefs.schemas.inputsLarger", {
    gradeNames: ["autoInit", "fluid.prefs.schemas"],
    schema: {
        "fluid.prefs.inputsLarger": {
            "type": "boolean",
            "default": true
        }
    }
});

fluid.uiOptions.prefsEditor("#myContainer", {
    tocTemplate: "html/myTocTemplate.html"
});


        </td>
    </tr>
</tbody>