UI Options API

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

UI Options

Parameters

componentContainer

The componentContainer parameter is a selector, a single-element jQuery, or a DOM element specifying the root DOM node of the UI Options markup.

NOTE: The default template UIOptions.html includes such a root DOM node, identified by the CSS selector ".uiOptions". If you wish to use the default template "out of the box," you can use this selector.

options

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

Supported Events

The UI Options 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

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.
`onSave`	default	This event fires just before the settings are saved.	`(model)`	`model`: The current (new) value of the "model" structure representing the settings in the component
`onCancel`	default	This event fires just before updating the model to the saved settings and refreshing the display.	none
`onReset`	default	This event fires just before updating the model to the default settings and refreshing the display.	none
`afterRender`	default	This event fires just after the options dialog has been rendered.	none

Functions and Properties

These functions and data structures are defined on the central that object returned from the uiOptions construction function - for example with

var that = fluid.uiOptions(componentContainer, options);

that.cancel();

Fires the onCancel event and reverts changes to the last time the selected options were saved. Sets that.model to uiEnhancer.model

that.refreshView();

Updates the UI Options settings in the DOM to match that.model.

that.reset();

Fires the onReset event and reverts to the default selections as specified by the integrator. Sets that.model to uiEnhancer.defaultSiteSettings

that.save();

Fires the onSave event and applies the UI Options settings to the entire page. Sets uiEnhancer.model to that.model

that.updateModel(newValue, source);

Updates the component's internal representation of the settings to a new value. The modelChanged event will fire and the preview will be restyled. Sets that.model to newValue

that.uiEnhancer

The uiEnhancer component that will be used to style the page, persist settings, set defaults etc.

that.model

The selections on the UI Options interface. External users should consider this structure as read-only, and only make modifications through the updateModel(), save(), cancel() and reset() functions above.

Options

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

Name	Description	Values	Default

Name	Description	Values	Default
`selectors`	Javascript object containing selectors for various fragments of the UI Options component.	The object can contain any subset of the following keys: `controls` `textMinSizeCtrl` `lineSpacingCtrl` `cancel` `reset` `save` `previewFrame` Any values not provided will revert to the default.	`selectors: { controls: ".flc-uiOptions-control", textMinSizeCtrl: ".flc-uiOptions-min-text-size", lineSpacingCtrl: ".flc-uiOptions-line-spacing", cancel: ".flc-uiOptions-cancel", reset: ".flc-uiOptions-reset", save: ".flc-uiOptions-save", previewFrame : ".flc-uiOptions-preview-frame" }` Please note: the `previewFrame` selector refers to the preview window iframe element. This iframe needs to include ALL the CSS dependencies mentioned below.
`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
`textMinSize`	A subcomponent that provides a control allowing users to specify the desired minimum text size.	A subcomponent specification `type: functionName,` `options: textMinSizeOptions`	`textMinSize: { type: "fluid.textfieldSlider", options: { min: 6, max: 30 } }` For more information about the options for the fluid:Textfield Slider see below.
`lineSpacing`	A subcomponent that provides a control allowing users to specify the desired line spacing.	A subcomponent specification `type: functionName,` `options: lineSpacingOptions`	`lineSpacing: { type: "fluid.textfieldSlider", options: { min: 1, max: 10 } }` For more information about the options for the fluid:Textfield Slider see below.
`strings`	Strings displayed on the UI Options interface. These relate to the fluid:control values below by array position.	A javascript object containing any subset of the following keys: `textFont` `textSpacing` `theme` `backgroundImages` `layout` `toc` The value for a key must be an array containing strings for each of the related fluid:control values below.	`strings: { textFont: ["Serif", "Sans-Serif", "Arial", "Verdana", "Courier", "Times"], textSpacing: ["Regular", "Wide", "Wider", "Widest"], theme: ["Low Contrast", "Medium Contrast", "Medium Contrast Grey Scale", "High Contrast", "High Contrast Inverted"], backgroundImages: ["Yes", "No"], layout: ["Yes", "No"], toc: ["Yes", "No"] }`
`controlValues`	The values that will be set for a control based on user interaction. These relate to the strings above by array position. uiEnhancer uses these values when transforming a page.	A javascript object containing any subset of the following keys: `textFont` `textSpacing` `theme` `backgroundImages` `layout` `toc` The value for a key must be an array containing values that are recognizable by uiEnhancer for each of the related strings above.	`controlValues: { textFont: ["serif", "sansSerif", "arial", "verdana", "courier", "times"], textSpacing: ["default", "wide1", "wide2", "wide3"], theme: ["lowContrast", "default", "mediumContrast", "highContrast", "highContrastInverted"], backgroundImages: ["true", "false"], layout: ["simple", "default"], toc: ["true", "false"] }`
New in v1.3: `previewTemplateUrl`	The URL that will load in the preview pane.	The full path to the file used for preview.	`previewTemplateUrl: "UIOptionsPreview.html"`