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
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
- a dialog (UIOptions.html), and
- a preview pane that is included in the dialog (UIOptionsPreview.html).
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.
This component is in Preview status
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 |
---|---|---|---|---|
|
default |
This event is fired any time the model for the component has changed, that is, when any of the settings are changed. |
|
|
|
default |
This event fires just before the settings are saved. |
|
|
|
default |
This event fires just before updating the model to the saved settings and refreshing the display. |
none |
|
|
default |
This event fires just before updating the model to the default settings and refreshing the display. |
none |
|
|
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 |
---|---|---|---|
|
Javascript object containing selectors for various fragments of the UI Options component. |
The object can contain any subset of the following keys: |
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" }
|
|
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. |
|
|
A subcomponent that provides a control allowing users to specify the desired minimum text size. |
A subcomponent specification |
textMinSize: { type: "fluid.textfieldSlider", options: { min: 6, max: 30 } }
|
|
A subcomponent that provides a control allowing users to specify the desired line spacing. |
A subcomponent specification |
lineSpacing: { type: "fluid.textfieldSlider", options: { min: 1, max: 10 } }
|
|
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: |
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"] } |
|
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: |
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: |
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 |
---|---|---|---|---|
|
default |
This event is fired any time the model for the component has changed, that is, when any of the settings are changed. |
|
|
options
Name |
Description |
Values |
Default |
---|---|---|---|
|
Javascript object containing selectors for various fragments of the Textfield Slider subcomponent. |
The object may contain any subset of the following keys: |
selectors: { textfield: ".flc-textfieldSlider-field", slider: ".flc-textfieldSlider-slider" } |
|
See fluid:Supported Events above for more information. |
|
events: { modelChanged: null } |
|
The Textfield Slider subcomponent uses jQuery's slider as its implementation. This field allows users to provide options other than |
For information about jQuery's slider options see the jQuery documentation. |
sliderOptions: { orientation: "horizontal" } |
|
The minimum value used by the slider. |
integer |
|
|
The maximum value used by the slider. |
integer |
|
|
The actual value to set the component to. |
integer |
|
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 -->