Tutorial - UI Options and UI Enhancer

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.

Step 1: Prepare your markup

Let's assume that you're starting with an HTML file, called home.html with the following content:


<body>
    <h1>Some Sample Title</h1>
    <p>Some content with <a id="myLink">a link</a> and<button id="myButton">a button</button>. </p>

    <!-- div that will contain the UI Options component -->
    <div id="myUIOptions">
    </div>
</body>

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

UI Options and UI Enhancer depend upon Fluid Skinning System (FSS) so the CSS files will need to be included. You'll also need to add the Fluid Infusion JavaScript to your HTML file. In the header of the file, link to the CSS files with <link> tags and the JavaScript files with <script> tags. Let's also link to a JavaScript file that we will create in fluid:step 3 (note the CSS files go first):


<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" />

<script type="text/javascript" src="InfusionAll.js"></script>
<script type="text/javascript" src="myInit.js"></script>

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.


(function ($, fluid) {

    //initialize the UI Enhancer
    var initUIEnhancer = function () {

        var enhancerOpts = {
            defaultSiteSettings: {
                theme: "mist",
                linksBold: true,
                linksUnderline: true
            },
            tableOfContents: {
                options: {
                    templateUrl: "components/tableOfContents/html/TableOfContents.html"
                }

            }
        };

        return fluid.uiEnhancer(document, enhancerOpts);
    };
})(jQuery, fluid);

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.


(function ($, fluid) {

    //initialize the UI Enhancer
    var initUIEnhancer = function () {

        var enhancerOpts = {
            defaultSiteSettings: {
                theme: "mist",
                linksBold: true,
                linksUnderline: true
            },
            tableOfContents: {
                options: {
                    templateUrl: "components/tableOfContents/html/TableOfContents.html"
                }

            }
        };

        return fluid.uiEnhancer(document, enhancerOpts);
    };

    //as soon as web document is loaded, initialize the UI Enhancer
    $(document).ready( function () {
        initUIEnhancer();
    });
})(jQuery, fluid);

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.


    //initialize UI Options component
    var initUIOptions = function () {
        return fluid.uiOptions(".uiOptions");
    };

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.


    //load the UI Options component
    var loadUIOptions = function () {
	var urlSelector = "components/uiOptions/html/UIOptions.html .uiOptions";
        uiOptionsNode.load(urlSelector, initUIOptions);
    };

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:


(function ($, fluid) {

    var uiOptionsNode;

    //initialize the UI Enhancer
    var initUIEnhancer = function () {

        var enhancerOpts = {
            defaultSiteSettings: {
                theme: "mist",
                linksBold: true,
                linksUnderline: true
            },
            tableOfContents: {
                options: {
                    templateUrl: "components/tableOfContents/html/TableOfContents.html"
                }

            }
        };

        return fluid.uiEnhancer(document, enhancerOpts);
    };

    //initialize UI Options component
    var initUIOptions = function () {
        return fluid.uiOptions(".uiOptions");
    };

    //load the UI Options component
    var loadUIOptions = function () {
        var urlSelector = "components/uiOptions/html/UIOptions.html .uiOptions";
        uiOptionsNode.load(urlSelector, initUIOptions);
    };

    //as soon as web document is loaded, initialize the UI Enhancer
    $(document).ready(function () {
        //use JQuery to find the dom node represented by myUIOptionsSelector
        uiOptionsNode = $("#myUIOptions"); //selector in which to load ui options
        initUIEnhancer();
        loadUIOptions();
    });

})(jQuery, fluid);

Reloading the 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:


     //initialize UI Options component
    var initUIOptions = function () {
        var options = {
            previewTemplateUrl: "components/uiOptions/html/UIOptionsPreview.html"
        };
        return fluid.uiOptions(".uiOptions", options);
    };

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:


     //initialize UI Options component
    var initUIOptions = function () {
        var options = {
            previewTemplateUrl: "mypreview.html"
        };
        return fluid.uiOptions(".uiOptions", options);
    };

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 home.html file.


<script type="text/javascript" src="lib/jquery/ui/js/ui.accordion.js"></script>

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 uiOptions.


    //initialize UI Options component
    var initUIOptions = function () {
        var options = {
            listeners: {
                afterRender: function () {
                    $(".uiOptions .fl-col:eq(0)").accordion({
                        header: 'h2',
                        clearStyle: true,
                        autoHeight: false
                    });
                    $(".uiOptions .fl-col h2:eq(0)").focus();
                }
            }
        };
        return fluid.uiOptions(".uiOptions", options);
    };

If you reload the home.html file you will see the accordian feature when you click on "Easier to see" or "Easier to find".