UI Options

The UI Options component works in conjunction with the UI Enhancer component and the Fluid Skinning System (FSS) to allow users to set personal user interface preferences. The UI Options component provides a user interface for setting and saving personal preferences, and the UI Enhancer component carries out the work of applying those preferences to the user interface.

Three version of UI Options are available:

Do not use this component directly. The information on this page should be use when customizing one of the three versions.

New in 1.4

(October, 2011)

The UI Options component has been completely refactored in version 1.4:

The component is now available in three versions: Full Page, Full Page with Preview, and Fat Panel.
The interface has been completely redesigned.
The API has been updated.

#Supported Events	`#modelChanged` Fires when the user changes an interface control. `#onAutoSave` Fires when the settings are about to be automatically saved. `#onCancel` Fires when the user cancels their changes to the settings. `#onReset` Fires when the user resets the settings. `#onSave` Fires when the settings are about to be saved. `#onUIOptionsComponentReady` Fires once the component has completed it's initialization. `#onUIOptionsRefresh` Fires whenever the settings have been saved or reset, or when changes are cancelled.
Methods	none
#Options	`#autoSave` A boolean indicating whether or not the setting will save automatically when changed. `listeners` See #Supported Events for information. `selectors` See below.
#Selectors	`#cancel` The 'cancel' button `#layoutControls` Container for the layout controls `#linksControls` Container for the links controls `#previewFrame` The `<iframe>` for the preview `#reset` The 'reset' button `#save` The 'save' button `#textControls` Container for the text controls

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.

modelChanged

Description	This event fires when the user adjusts one of the controls in the UI Options interface.
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.3 and later
See also	Firing a change using a ChangeApplier

onAutoSave

Description	When the `#autoSave` option is set to `true`, this event fires before the settings are automatically saved. Note that this is not a "preventable" event.
Type	default
Parameters	none
Availability	Infusion 1.3 and later
See also	Event Types

onCancel

Description	This event fires when the use cancels any changes to the settings, before the settings are restore to their previous values.
Type	default
Parameters	none
Availability	Infusion 1.3 and later

onReset

Description	This event fires when the use resets the settings, before the settings are restore to the site's default values.
Type	default
Parameters	none
Availability	Infusion 1.3 and later

onSave

Description	This event fires when the user saves the settings, before the new settings are recorded in the settings store.
Type	default
Parameters	selections A JavaScript object containing the user's selections.
Availability	Infusion 1.3 and later
See also	Cookie Settings Store

onUIOptionsComponentReady

Description	This event fires after the UI Options component has loaded its templates and attached any event handlers. This event triggers the creation of the subcomponents relating to the different settings.
Type	default
Parameters	that The UI Options component object
Availability	Infusion 1.4 and later

onUIOptionsRefresh

Description	This event fires any time the settings are saved or reset, or when the user cancels their changes to the interface.
Type	default
Parameters	none
Availability	Infusion 1.4 and later

Options

back to top

autoSave

Description	A boolean indicating whether or not the setting will save automatically when changed.
Default	`false`
Example	options: { autoSave: true }

selectors

Description	A JavaScript object identifying CSS-based selectors for DOM elements that are of interest to the component. See #Selectors below for details.
See also	#Selectors

Selectors

back to top

One of the options that can be provided to the component is a set of CSS-based selectors identifying where in the DOM different elements can be found. The value for the option is itself a Javascript object containing name/value pairs:

selectors: {
    selector1Name: "selector 1 string",
    selector2Name: "selector 2 string",
      ...
}

The component defines defaults for these selectors: If you use those defaults in your markup, you do not need to specify the selectors option. If you do choose to override any of the selectors, you can specify your custom selector using this option.

The selectors supported by UI Options are described below.

cancel

Description	The "cancel" button.
Default	".flc-uiOptions-cancel"
Example	selectors: { cancel: "#myCancelButton" }

layoutControls

Description	Container where the layout controls will be rendered. This will typically be an empty `div`.
Default	".flc-uiOptions-layout-controls"
Example	selectors: { layoutControls: ".layout-controls" }
See also	Layout Controls

linksControls

Description	Container where the links controls will be rendered. This will typically be an empty `div`.
Default	".flc-uiOptions-links-controls"
Example	selectors: { linksControls: "div.links-controls-container" }
See also	Links Controls

previewFrame

Description	The `<iframe>` to be used for the preview (in the case of the Full With Preview version of UI Options).
Default	".flc-uiOptions-preview-frame"
Example	selectors: { previewFrame: "#previewIFrame" }
See also	Preview

reset

Description	The "reset" button.
Default	".flc-uiOptions-reset"
Example	selectors: { reset: ".resetButton" }

save

Description	The "save" button.
Default	".flc-uiOptions-save"
Example	selectors: { save: "input.save-button" }

textControls

Description	Container where the text controls will be rendered. This will typically be an empty `div`.
Default	".flc-uiOptions-text-controls"
Example	selectors: { textControls: "#myTextControls" }
See also	Text Controls