Documentation for a historical release of Infusion: 1.4
Please view the Infusion Documentation site for the latest documentation, or the Infusion 1.3. Documentation for the previous release.
If you're looking for Fluid Project coordination, design, communication, etc, try the Fluid Project Wiki.

UI Enhancer

This documentation applies to v1.4 of UI Options.
For earlier versions, see
UI Enhancer API.

Production Status: PREVIEW

The User Interface Options component (UI Options) works in conjunction with the User Interface Enhancer component (UI Enhancer) and the Fluid Skinning System (FSS) to adjust the user interface based on personal preferences:

  • UI Options presents the user with controls for adjusting preferences.
  • UI Enhancer is the engine that transforms pages according to the saved preferences.

See Also
Tutorial - Page Enhancer
Full Page UI Options
Full Page UI Options (with Preview)
Fat Panel UI Options

New in 1.4 (September, 2011)

  • Code refactored
  • API changed

#Creators

#fluid.uiEnhancer(container, options)
#fluid.pageEnhancer(options)

#Supported Events

#onCreateTOCReady
Fires when table of content can be created

#modelChanged
Fires when any settings have changed

Methods

none

#Options

#classnameMap
A mapping between controls and CSS classnames used for those preferences

#fontSizeMap
A mapping between string values of "font-size" and the actual numerical values in px

#px2emFactor
A factor to convert px value to em value

#defaultSiteSettings
Default values for each of the settings

listeners
See #Supported Events for information.

#tocTemplate
Path to the template file for the Table of Contents

#Subcomponents

#settingsStore
Provides access to the saved settings.

#tableOfContents
Presents a links of links to headings on the page.

Creators

back to top

Use one of the following functions to create a UI Enhancer component:

fluid.uiEnhancer(container, options)

Method

fluid.uiEnhancer(container, options);

Description

Instantiates a UI Enhancer component applied to the specified container.

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 Enhancer component

Examples

var uie = fluid.uiEnhancer("#main");

See also

#fluid.pageEnhancer(options)

fluid.pageEnhancer(options)

Method

fluid.pageEnhancer(options);

Description

Instantiates a UI Enhancer component applied to the entire current page.

Parameters

options
An optional data structure that configures the UI Options component, as described below.

Returns

The UI Enhancer component

Examples

var enhancer = fluid.pageEnhancer();

See also

#fluid.uiEnhancer(container, options)

Supported Events

back to top

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.

onCreateTOCReady

Description

This event fires when the "table of content" preference is turned on and the DOM is fully loaded. This event triggers the creation of the Table of Contents subcomponent.

Type

default

Parameters

none

Availability

Infusion 1.4 and later

modelChanged

Description

This event fires when any settings have changed.

Type

default

Parameters

newModel
The overall model containing the user's current selections.

oldModel
A "snapshot" of the previous state of the model, before the change.

changeRequest
The original change request object.

Availability

Infusion 1.4 and later

See also

Firing a change using a ChangeApplier

Options

back to top

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.

classnameMap

Description

A mapping between controls and CSS classnames used for those preferences. The classnames defined using this option are applied to the document in response to user preferences.

Default

classnameMap: {
    "textFont": {
        "default": "",
        "times": "fl-font-times",
        "comic": "fl-font-comic-sans",
        "arial": "fl-font-arial",
        "verdana": "fl-font-verdana"
    },
    "theme": {
        "default": "",
        "bw": "fl-theme-uio-hc fl-theme-hc",
        "wb": "fl-theme-uio-hci fl-theme-hci",
        "by": "fl-theme-uio-blackYellow fl-theme-blackYellow",
        "yb": "fl-theme-uio-yellowBlack fl-theme-yellowBlack"
    },
    "layout": "fl-layout-linear",
    "links": "fl-text-underline fl-text-bold fl-text-larger", 
    "inputsLarger": "fl-text-larger"
}

Example

var enh = fluid.pageEnhancer({
    classnameMap: {
        theme: {
            "default": "my-custom-theme"
        }
    }
});

Notes

If you have a custom theme for your site, you should use the classnameMap to set the default theme name.

See also

Tutorial - Page Enhancer
Fluid Skinning System (FSS)

fontSizeMap

Description

A mapping between string values of "font-size" and the actual numerical values in px. The option is necessary for "Text Size" preference working properly in IE6 & IE7.

Default

fontSizeMap: {
    "xx-small": "9px",
    "x-small":  "11px",
    "small":    "13px",
    "medium":   "15px",
    "large":    "18px",
    "x-large":  "23px",
    "xx-large": "30px"
}

Example

var enh = fluid.pageEnhancer({
    fontSizeMap: {
        "medium": "16px"
    }
});

Notes

The actual numerical value translations of the "font-size" string values vary depending on the OS display setting. If your computer is set to view in larger or smaller font, you need to adjust fontSizeMap to the desired mapped-to values.

See also

Tutorial - Page Enhancer
Fluid Skinning System (FSS)
CSS font-size Property

px2emFactor

Description

A factor to convert px value to em value. This value is used by "Text Size" preference to adjust body "font-size" in em

Default

16

Example

var enh = fluid.pageEnhancer({
    px2emFactor: "10"
});

Notes

The factor varies depending on the "font-size" set on <body>. Refer to PX to EM conversion to adjust the factor value to what you need.

See also

Tutorial - Page Enhancer
Fluid Skinning System (FSS)
PX to EM conversion

Subcomponents

Subcomponents can be configured though the parent component's components option using the following pattern:

parent.component.name(".myContainer", {
    components: {
        <subcomponentName>: {
            options: {
                <subcomponent options>
            }
        }
    }
});

settingsStore

Description

The settingsStore subcomponent manages the storage and retrieval of the current settings, including default settings. Two implementations are provided with Infusion.

Default implementation

fluid.cookieStore

Alternate implementation

fluid.tempStore

Example

fluid.uiEnhancer(".myContainer", {
    components: {
        settingsStore: {
            options: {
                cookie: {
                    expires: "Mon, 31 Dec 2012 23:59:00 UTC"
                }
            }
        }
    }
});

See also

Cookie Settings Store
Temporary Settings Store

tableOfContents

Description

The tableOfContents subcomponent generates and renders a list of links to the headings on the page.

Default implementation

fluid.tableOfContents

Example

fluid.pageEnhancer(".myContainer", {
    components: {
        tableOfContents: {
            options: {
                selectors: {
                    tocContainer: ".custom-tocContainer"
                }
            }
        }
    }
});

See also

Table of Contents