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

UI Enhancer API

Owned by Anastasia Cheetham
Last updated: Apr 03, 2013 by Former user (Deleted)Version comment
6 min read

This documentation applies to v1.3 and earlier. For UI Enhancer API information for v1.4 and later, please see the UI Enhancer in the new documentation space.

UI Enhancer

The UI Enhancer component works in conjunction with (Floe) UI Options (2008-2009) component and the Fluid Skinning System (FSS) to adjust the user interface based on personal user interface preferences. The settings that are currently supported are:

  • themes,
  • text size,
  • text and line spacing,
  • font family,
  • whether or not background images show
  • simplified layout
  • table of contents
  • input and link highlighting

Subcomponents

The Fluid UI Enhancer, like many Fluid components, uses various subcomponents in its lifecycle. In particular, the UI Enhancer uses the following subcomponents:

These subcomponents are instantiated and managed by the UI Enhancer, but each has options that can be used to configure and customize it.

Creation

fluid.uiEnhancer();
fluid.uiEnhancer(document, options);

Return: The UI Enhancer component object.
There is a single UI Enhancer per document and it stores itself on the document using jQuery.data

Parameters

document

The document parameter is a selector, a single-element jQuery, or a document specifying the document that will be transformed.

Status

This component is in Preview status

On This Page
See Also
Still need help?

Join the infusion-users mailing list and ask your questions there.

options

The options parameter is an optional data structure that configures the UI Enhancer component, as described below in the fluid:Options section of this page .

Supported Events

The UI Enhancer component fires the following events (for more information about events in the Fluid Framework, see Events for Component Users):

Event

Type

Description

Parameters

Parameter Description

modelChanged

default

This event is fired any time the model for the component has changed, that is, when any of the settings are changed.

(model, oldModel, source)

model: The current (new) value of the "model" structure representing the settings in the component
oldModel: A snapshot of the old value of the model structure before the current change
source: An arbitrary object which optionally represents the "source" of the change, which can be checked by listeners to prevent cyclic events. Can often be undefined.

Functions and Properties

These functions and properties are defined on the central that object returned from the uiEnhancer construction function - for example with 

var that = fluid.uiEnhancer(document, options);

that.refreshView();

Applies the settings in that.model to the DOM - restyles the markup, adds a table of contents, etc. 

that.updateModel(newValue, source);

Updates the component's internal representation of the settings to a new value. The modelChanged event will fire and that.model is set to newValue

that.container

The body of the document.

that.defaultSiteSettings

The default site settings as defined by the integrator. 

that.model

The settings that the UI Enhancer will apply.

that.settingsStore

The persistence strategy for the settings - defaults to a cookieStore.

Options

The following options to the creator function can be used to customize the behaviour of the UI Enhancer component:

Name

Description

Values

Default

listeners

JavaScript object containing listeners to be attached to the supported events.

Keys in the object are event names, values are functions or arrays of functions.

See fluid:Supported Events

defaultSiteSettings

JavaScript object containing the user's last saved selections

The object can contain any subset of the keys.
Note: It is important to specify the defaults that your site displays with here. This information is used when determining how to apply settings. 

defaultSiteSettings: {
    textFont: "",                 // key from classnameMap
    textSpacing: "default",       // key from classnameMap
    theme: "default",             // key from classnameMap
    layout: "default",            // key from classnameMap
    textSize: "",                 // in points
    lineSpacing: "",              // in ems
    backgroundImages: true,       // boolean
    toc: false,                   // boolean
    linksUnderline: false,        // boolean
    linksBold: false,             // boolean
    linksLarger: false,           // boolean
    inputsLarger: false           // boolean
}

see fluid:classnameMap

savedSettings

JavaScript object containing the user's last saved selections

The object can contain any subset of the keys. defaultSiteSettings is an example of what this object may look like

none

settingsStore

A subcomponent that handles persistence of settings

subcomponent configuration 

settingsStore: {
    type: "fluid.uiEnhancer.cookieStore"
}


For more information about the Cookie Store subcomponent, see #Cookie Store subcomponent below.

tableOfContents

A subcomponent that inserts a table of contents

subcomponent configuration 

tableOfContents: {
    type: "fluid.tableOfContents",
    options: {
        templateUrl: "../../tableOfContents/html/TableOfContents.html"
    }
}


For more information about the Table of Contents subcomponent, see Table of Contents API.

classnameMap

A mapping of setting values to FSS classnames

A javascript object containing any subset of setting values and their corresponding FSS class names. This is where you would override the styling of a particular setting choice. 

classnameMap: {
    "textFont": {
        "serif": "fl-font-serif",
        "sansSerif": "fl-font-sans",
        "arial": "fl-font-arial",
        "verdana": "fl-font-verdana",
        "monospace": "fl-font-monospace",
        "courier": "fl-font-courier",
        "times": "fl-font-times"
    },
    "textSpacing": {
        "default": "",
        "wide0": "fl-font-spacing-0",
        "wide1": "fl-font-spacing-1",
        "wide2": "fl-font-spacing-2",
        "wide3": "fl-font-spacing-3",
        "wide4": "fl-font-spacing-4",
        "wide5": "fl-font-spacing-5",
        "wide6": "fl-font-spacing-6"
    },
    "theme": {
        "mist": "fl-theme-mist",
        "rust": "fl-theme-rust",
        "highContrast": "fl-theme-hc",
        "highContrastInverted": "fl-theme-hci",
        "lowContrast": "fl-theme-slate",
        "mediumContrast": "fl-theme-coal",
        "default": ""
    },
    "layout": {
        "simple": "fl-layout-linear",
        "default": ""
    },
    "noBackgroundImages": "fl-no-background-images",
    "linksUnderline": "fl-text-underline", 
    "linksBold": "fl-text-bold", 
    "linksLarger": "fl-text-larger", 
    "inputsLarger": "fl-text-larger"
}

Cookie Store subcomponent

The Cookie Store is used to record a set of UI preferences for later retrieval by the UI Enhancer. It is the default settings store shipped with the UI Enhancer component.

Subcomponent Name: fluid.uiEnhancer.cookieStore

Functions

A settings store subcomponent implements two functions, fetch and save.

that.fetch = function () {
};

This function retrieves and returns the value of the stored settings (i.e. the stored cookie).

that.save = function (settings) {
};

This function saves (stores) the settings in a cookie.

options

Name

Description

Values

Default

cookieName

The name used for the stored cookie.

string 

cookieName: "fluid-ui-settings"

Temp Store subcomponent

The Temp Store is a settings store subcomponent that provides temporary storage of preferences, without persistance.

Subcomponent Name: fluid.uiEnhancer.tempStore

Functions

A settings store subcomponent implements two functions, fetch and save.

that.fetch = function () {
};

This function retrieves and returns the value of the stored settings from memory.

that.save = function (settings) {
};

This function saves the settings in memory.

The Temp Store subcomponent has no default options.

Dependencies

The UI Options component depends on the Fluid Skinning System and as such the following style-sheets are required:

<link rel="stylesheet" type="text/css" href="framework/fss/css/fss-reset.css" />
<link rel="stylesheet" type="text/css" href="framework/fss/css/fss-layout.css" />
<link rel="stylesheet" type="text/css" href="framework/fss/css/fss-text.css" />
<link rel="stylesheet" type="text/css" href="framework/fss/css/fss-theme.hc.css" />
<link rel="stylesheet" type="text/css" href="framework/fss/css/fss-theme.hci.css" />
<link rel="stylesheet" type="text/css" href="framework/fss/css/fss-theme.mist.css" />
<link rel="stylesheet" type="text/css" href="framework/fss/css/fss-theme.rust.css" />
<link rel="stylesheet" type="text/css" href="framework/fss/css/fss-theme.coal.css" />
<link rel="stylesheet" type="text/css" href="framework/fss/css/fss-theme.slate.css" />

The UI Enhancer javascript dependencies can be met by including the minified InfusionAll.js file in the header of the HTML file. 

<script type="text/javascript" src="InfusionAll.js"></script>

Alternatively, the individual javascript file requirements are:


<script type="text/javascript" src="lib/jquery/core/js/jquery.js"></script>
<script type="text/javascript" src="framework/core/js/Fluid.js"></script>
<script type="text/javascript" src="framework/core/js/FluidRequests.js"></script>
<script type="text/javascript" src="lib/fastXmlPull/js/fastXmlPull.js"></script>
<script type="text/javascript" src="framework/renderer/js/fluidParser.js"></script>
<script type="text/javascript" src="framework/renderer/js/fluidRenderer.js"></script>
<script type="text/javascript" src="lib/json/js/json2.js"></script>
<script type="text/javascript" src="components/tableOfContents/js/TableOfContents.js"></script>
<script type="text/javascript" src="components/uiOptions/js/UIEnhancer.js"></script>