Full Page UI Options (with Preview)

This documentation applies to v1.4 of UI Options.
For earlier versions, see
UI Options API.

Production Status: PREVIEW

The User Interface Options component (UI Options) works in conjunction with the User Interface Enhancer component (UI Enhancer) and the Fluid Skinning System (FSS) to adjust the user interface based on personal preferences:

UI Options presents the user with controls for adjusting preferences.
UI Enhancer is the engine that transforms pages according to the saved preferences.

The Full Page (with Preview) version of UI Options displays the UI Options controls in a standalone page, with a Preview pane that is updated as the user adjusts the controls.

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.

#Creator	`fluid.uiOptions.fullPreview(container, options)`
Supported Events	none
Methods	none
#Options	`#prefix` A relative path to templates.
#Configurable Subcomponents	`#layoutControls` The `layoutControls` subcomponent renders the controls for customizing the layout of the page. `#linksControls` The `linksControls` subcomponent renders the controls for customizing the appearance of links on the page. `#preview` The `preview` subcomponent is responsible for rendering the live preview. `#previewEnhancer` The `previewEnhancer` subcomponent is the UI Enhancer for the preview. `#templateLoader` The `templateLoader` subcomponent is responsible for fetching HTML templates for the various controls. `#textControls` The `textControls` subcomponent renders the controls for customizing the appearance of text on the page. `#uiOptions` The `uiOptions` subcomponent is responsible for the main rendering of the controls.

Creator

back to top

Use the following function to create a Full Page UI Options with Preview component:

Method	`fluid.uiOptions.fullPreview(container, options);`
Description	Instantiate a full-page version of the UI Options component, with a live Preview.
Parameters	`container` A CSS-based selectors, single-element jQuery object, or DOM element that identifies the root DOM node where the UI Options interface should be placed. `options` An optional data structure that configures the UI Options component, as described below.
Returns	The Full Page (with Preview) UI Options component
Examples	var myUIO = fluid.uiOptions.fullPreview(#myContainer, { prefix: ".././components/uiOptions/html/" });
Notes
See also	Full Page UI Options Fat Panel UI Options

Options

back to top

The second argument to the creator function is the options argument. This is a JavaScript object containing name/value pairs: The name is the name of the option and the value is the desired setting. Components define their own default values for options, but integrators can override these defaults by providing new values using the options argument. For technical information about how options are merged with defaults, see Options Merging.

var fullUIO = fluid.uiOptions.fullPreview(".myContainer", {
    <option1Name>: <option1value>,
    <option2Name>: <option2value>
    ...
}
});

The options supported by Full Page UI Options (with Preview) are described below.

prefix

Description	The `prefix` option allows you to specify a custom relative path to the templates used by the UI Options interface. These templates can be found in the source tree of the Infusion distribution. The value of the `prefix` option will be passed on to the Template Loader subcomponent.
Default	"../html/"
Example	fluid.uiOptions.fullNoPreview("#myContainer", { prefix: "../../components/uiOptions/html/" });
Notes	Note that if the Template Loader values do not use the `%prefix` notation, the value of the `prefix` option will be ignored.
See also	Template Loader

Configurable Subcomponents

Configurable subcomponents can be configured though the parent component's options by passing a JavaScript object containing options for the subcomponent:

parent.component.name(".myContainer", {
    <subcomponentName>: {
        options: {
            <subcomponent options>
        }
    }
});

To learn about the specific options for each subcomponent, visit the default implementation's API page.

layoutControls

Description	The `layoutControls` subcomponent renders the controls for customizing the layout of the page.
Default implementation	`fluid.uiOptions.layoutControls`
Example	fluid.uiOptions.fullPreview(".myContainer", { layoutControls: { options: { listeners: { onUIOptionsRefresh: myRefreshListener } } } });
See also	Layout Controls

linksControls

Description	The `linksControls` subcomponent renders the controls for customizing the appearance of links on the page.
Default implementation	`fluid.uiOptions.linksControls`
Example	fluid.uiOptions.fullPreview(".myContainer", { linksControls: { options: { listeners: { onUIOptionsRefresh: myRefreshListener } } } });
See also	Links Controls

preview

Description	The `preview` subcomponent is responsible for rendering the live preview.
Default implementation	`fluid.uiOptions.preview`
Example	fluid.uiOptions.fullPreview(".myContainer", { preview: { options: { templateUrl: "../templates/CustomPreviewTemplate.html" } } });
See also	Preview

previewEnhancer

Description	The `previewEnhancer` subcomponent is the UI Enhancer that is applied to the preview.
Default implementation	`fluid.uiEnhancer`
Example	fluid.uiOptions.fullPreview(".myContainer", { previewEnhancer: { options: { classnameMap: { theme: { "default": "site-theme" } } } } });
See also	UI Enhancer

templateLoader

Description	The `templateLoader` subcomponent is responsible for fetching HTML templates for the various controls.
Default implementation	`fluid.uiOptions.templateLoader`
Example	fluid.uiOptions.fullPreview(".myContainer", { templateLoader: { options: { templates: { linksControls: "../templates/CustomLinksTemplate.html" } } } });
See also	Template Loader

textControls

Description	The `textControls` subcomponent renders the controls for customizing the appearance of text on the page.
Default implementation	`fluid.uiOptions.textControls`
Example	fluid.uiOptions.fullPreview(".myContainer", { textControls: { options: { listeners: { onUIOptionsRefresh: myRefreshListener } } } });
See also	Text Controls

uiOptions

Description	The `uiOptions` subcomponent is responsible for the main rendering of the controls.
Default implementation	`fluid.uiOptions`
Example	fluid.uiOptions.fullPreview(".myContainer", { uiOptions: { options: { autoSave: false } } });
See also	UI Options