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 Options API

Owned by Michelle D'Souza
Last updated: Apr 03, 2013 by Joanna VassVersion comment
7 min read

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

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.

The settings that are currently supported are:

  • themes
  • text size
  • text and line spacing
  • font family
  • show/hide background images
  • simplified layout
  • table of contents
  • input and link highlighting

The UI Options interface may be implemented as a dialog (though this is not required). In this case, the implementer should provide a control such as a button or link which activates the dialog. For example, in the UI Options Sakai Integration Demo , the "Edit Appearance" button activates the UI Options dialog.

Implementers are free to provide their own markup for this dialog and a preview of the changes, but Fluid Infusion includes two template files for this interface

NOTE: UI Options requires a UI Enhancer to be instantiated on the page before being created.

Subcomponents

UIOptions, like many other components, uses subcomponents for some of its user interface. UI Options uses the Textfield Slider subcomponent as the control for the minimum text size and line spacing controls. fluid:Textfield Slider has its own configuration options described below.

Creation

fluid.uiOptions(componentContainer, options);

Return: The UI Options component object.

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.

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

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

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"

Textfield Slider subcomponent

The Textfield Slider subcomponent is a small user interface control that combines a textfield and a slider, tying them together so that changes to one of these controls are automatically reflected in the other.

Subcomponent Name: fluid.textfieldSlider

Supported Events

The Textfield Slider subcomponent 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.

options

Name

Description

Values

Default

selectors

Javascript object containing selectors for various fragments of the Textfield Slider subcomponent.

The object may contain any subset of the following keys:
   textfield
   slider
Any values not provided will revert to the default. 

selectors: {
    textfield: ".flc-textfieldSlider-field",
    slider: ".flc-textfieldSlider-slider"
}

events

See fluid:Supported Events above for more information.

 

 
events: {
    modelChanged: null
}

sliderOptions

The Textfield Slider subcomponent uses jQuery's slider as its implementation. This field allows users to provide options other than min, max and value, to be passed directly to jQuery.

For information about jQuery's slider options see the jQuery documentation. 

sliderOptions: {
    orientation: "horizontal"
}

min

The minimum value used by the slider.

integer

min: 0

max

The maximum value used by the slider.

integer

max: 100

value

The actual value to set the component to.

integer

value: null

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" />
<link rel="stylesheet" type="text/css" href="components/uiOptions/css/UIOptions.css" />
<link rel="stylesheet" type="text/css" href="components/uiOptions/css/Slider.css" />

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

<!-- jQuery files -->
<script type="text/javascript" src="lib/jquery/core/js/jquery.js"></script>
<script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.core.js"></script>
<script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.widget.js"></script>
<script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.mouse.js"></script>
<script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.accordion.js"></script>
<script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.slider.js"></script>

<script type="text/javascript" src="lib/json/js/json2.js"></script>

<!-- Infusion files -->
<script type="text/javascript" src="framework/core/js/jquery.keyboard-a11y.js"></script>
<script type="text/javascript" src="framework/core/js/Fluid.js"></script>
<script type="text/javascript" src="framework/core/js/FluidRequests.js"></script>  <!-- New in v1.3 -->
<script type="text/javascript" src="framework/core/js/FluidDOMUtilities.js"></script>
<script type="text/javascript" src="framework/core/js/DataBinding.js"></script>
<script type="text/javascript" src="framework/core/js/FluidIoC.js"></script>  <!-- New in v1.4 -->
<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="framework/renderer/js/RendererUtilities.js"></script>
<script type="text/javascript" src="components/uiOptions/js/Store.js"></script>  <!-- New in v1.4 -->
<script type="text/javascript" src="components/uiOptions/js/UIEnhancer.js"></script>
<script type="text/javascript" src="components/uiOptions/js/UIOptions.js"></script>
<script type="text/javascript" src="components/tableOfContents/js/TableOfContents.js"></script>

<!-- for Full-Page UI Options only: -->
<script type="text/javascript" src="components/uiOptions/js/FullNoPreviewUIOptions.js"></script>  <!-- New in v1.4 -->

<!-- for Full-Page With Preview UI Options only: -->
<script type="text/javascript" src="components/uiOptions/js/FullPreviewUIOptions.js"></script>  <!-- New in v1.4 -->

<!-- for Fat-Panel UI Options only: -->
<script type="text/javascript" src="components/uiOptions/js/URLUtilities.js"></script>  <!-- New in v1.4 -->
<script type="text/javascript" src="components/uiOptions/js/FatPanelUIOptions.js"></script>  <!-- New in v1.4 -->
<script type="text/javascript" src="components/uiOptions/js/SlidingPanel.js"></script>  <!-- New in v1.4 -->