This tutorial applies to v1.3 and earlier. For tutorials explaining how to use UIOptions v1.4 and later, please see the How-to Guides in the new documentation space.
This page will walk you through an example of adding the Fluid UI Options and UI Enhancer to a website.
This tutorial assumes that:
- you are familiar with what the UI Options and UI Enhancer are and do
- now you just want to know how to add them to your application.
UI Options requires UI Enhancer in order to apply the settings a user selects. UI Enhancer could be used alone in order to apply some effects to a page however its real power is when used in conjunction with UI Options. For more general information about UI Options see User Interface Options Version A Design Overview. For technical API documentation, see UI Options API and UI Enhancer API.
Tutorial: How to Use UI Options and UI Enhancer
You'd like to allow visitors to customize the presentation of your website to their individual needs, such as enlarging the text, or increasing the visual contrast. This tutorial will show you how to use the Fluid UI Options in a dialog to do this.
The basic steps to add UI Options and UI Enhancer to your application are:
- Step 1: Prepare your markup
- Step 2: Add dependencies to the markup
- Step 3: Write the script to create a UI Enhancer
- Step 4: Write the script to create a UI Options
- Step 5: Create the preview
- Step 6 (Optional): Use an accordian to simplify the interface
- Step 7 (Optional): Turn UI Options into a dialog
- Step 8 (Optional): Add UI Enhancer to other pages on your site
The rest of this tutorial will explain each of these steps in detail.
Setup: Download and install the Fluid Infusion library
- Download a copy of the Fluid Infusion component library from:
You only really need the "Minified deployment package," but if you want to actually look at the code, you should download the "Source package."
- Unpack the zip file you just downloaded, and place the resulting folder somewhere convenient for your development purposes.
The folder will have the release number in its name (e.g. infusion-1.4/). The rest of this tutorial will use infusion-1.4 in its examples, but if you downloaded a different version, you'll have to adjust.
Step 1: Prepare your markup
Let's assume that you're starting with an HTML file, called
home.html with the following content:
The UI Options component needs to know about the 'container' for the preference setting user interface. We will use an ID based selector of "myUIOptions" when creating the UI Options component below.
Step 2: Add dependencies to the markup
NOTE that the
InfusionAll.js file is minified - all of the whitespace has been removed, so it isn't really human-readable. If you're using the source distribution and you want to be able to debug the code, you'll want to include each of the required files individually. Instead of including InfusionAll.js you would include this:
But all of these individual files are not necessary to make it work - the
InfusionAll.js file has everything you need.
If you now load your
home.html file in a browser you will see the sample content.
Step 3: Write the script to create a UI Enhancer
You'll need to create a file, say
myInit.js, to contain your initialization script.
UI Options depends upon UI Enhancer and requires that a UI Enhancer is already on the page. So the first thing we will do is write a function to initialize the UI Enhancer.
When initializing the UI Enhancer it is important that we set the defaults that we want our site to display with, otherwise the default appearance of our site may be altered by the UI Enhancer. The defaults are set using the FSS and numeric and boolean values. See the UI Enhancer API for details about the defaultSiteSettings options. In this example, our site is based on the FSS theme 'mist', and uses bold, underlined links as the defaults.
The UI Enhancer has a Table of Contents subcomponent that has its own options. One of its options is an URL from which the template for a table of contents will be loaded. You will likely need to override the default URL as is done below.
We still need to call our initialization function but we must ensure the document is ready. This is accomplished in the document ready block below.
If you reload the
home.html page, you will see that the default styles have been applied.
Step 4: Write the script to create a UI Options
Now create an initialization function for the UI Options component. The first parameter to the
fluid.uiOptions is the container DOM element
uiOptions, which can be found on the UI Options template. The second parameter is our default options for the UIOptions component - we need to specify the URL to content for the preview pane.
Currently you need to load the UI Options template yourself although this will be fixed in FLUID-2616. Use jQuery to load the section of the template that is required - the form with the
uiOptions class on it. The template is loaded into the DOM node identified by #myUIOptions in
home.html. Use jQuery to find this node.
Don't forget to define
uiOptionsNode and call
loadUIOptions in your document ready block. You should also declare
uiOptionsNode at the beginning so its available to other functions. When you are finished your code will look something like this:
home.html file will show the UI Options component on the page. Note that the preview window has not loaded.
Step 5: Create the preview
Using the default preview
The preview for UI Options is displayed within an IFrame. There is a default preview file that ships with Fluid Infusion - if you want to use this preview, simply copy
components/uiOptions/UIOptionsPreview.html into the same directory as
home.html and it will be loaded into the IFrame. Note that for the preview to work it will need access to the CSS files that are linked to in the head of the
UIOptionsPreview.html file. Ensure that these have the correct paths.
Another option, instead of copying the default file to another directory, is to specify any file as an option called "previewTemplateUrl". Options are sent as the second parameter when calling the UIOptions component, so setting the preview template url would work like this:
Guidelines for building a custom preview
It is more likely that you will want the preview to contain something that better reflects your site. For a preview to be an accurate portrayal of how UI Options can alter your site, it's important to use a variety of different markup tags. Don't just take a paragraph of plain text from one page as your preview - rather, try to include headings, links, form controls, graphics, lists, and tables for a more complete site preview.
Create a file with sample content called "mypreview.html" in the same directory as home.html. Alter your UI Options initialization function as follows to implement your preview:
If you reload your
home.html page now, you will see the preview and be able to use the controls in the UI Options component. The UI Enhancer will remember your saved settings and apply them the next time you load this page. By default, the UI Enhancer uses a cookie to store your settings.
Step 6 (Optional): Use an accordian to simplify the interface
The UI Options interface can get be quite busy given all the setting controls. To simplify the interface you may want to use an accordian to hide and show parts of the UI Options form. We will use jQuery accordian plugin. If you are not using the
InfusionAll.js file, you will need to load the
ui.accordian.js file in the head of the
Now we will modify the
initUIOptions function we created in fluid:step 4. We will add an
afterRender listener to the UI Options component and include there the declarations needed to decorate the component with an accordian. Don't forget to pass the newly created
options variable to
If you reload the
home.html file you will see the accordian feature when you click on "Easier to see" or "Easier to find".
Step 7 (Optional): Turn UI Options into a dialog
You may want the UI Options component to be displayed in a dialog. Here you can use the jQuery dialog plugin. If you are not using the
InfusionAll.js file, you will need to load the
ui.dialog.js file in the head of the
In addition, you will want to modify the html slightly by adding another <div> and a <button> as shown below. We will use an ID based selector of "dialogContent" for this purpose.
myInit.js file add a
setupDialog function that creates a jQuery dialog and sets it to open when the
myButton button is clicked. In your HTML, take care to place your
myButton button in a place that is easily discoverable to your users.
You may want to set some options in the dialog that will make it look a little nicer than the default. Also modify
initUIOptions adding listeners to the
onCancel functions that will close the dialog.
home.html page now will result in the UI Options component disappearing from the page. Clicking the button will pop up the dialog, however, the dialog will be transparent. Applying the classes
fl-grabbable on the dialog should take care of this issue:
Another issue that you may notice is that if you make a change and then close the dialog the change is remembered the next time the dialog is opened, which is not the way a dialog is supposed to behave. Because this is a modal dialog, one way to address this issue is to de-activate the close functionality (use css to hide the close link and set closeOnEscape to false).
Step 8 (Optional): Add UI Enhancer to other pages on your site
Your site may not have the UI Options interface available on every page, however, you do want your users settings to be applied to your entire site. In order to do this you will need to add a UI Enhancer to every page by following the instructions in fluid:step 3.