Tutorial - Full Page UI Options

This tutorial applies to v1.4 of UI Options.
For earlier versions, see
Tutorial - UI Options and UI Enhancer.

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 version of UI Options displays the interface controls in a separate page. This tutorial will walk you through the process of setting up the full page version of UI Options.

NOTE that the UI Options component is pretty much useless without the UI Enhancer added to the pages of your site, so we highly recommend you visit the UI Enhancer tutorial to learn how to add the UI Enhancer to the pages of your site.

This tutorial assumes that:

you are already familiar with HTML, Javascript and CSS,
you are familiar with what the UI Options and UI Enhancer are and do, and
now you just want to know how to add them to your application.

Scenario

You're putting together a website that you know will have a diverse audience. You'd like to allow your visitors to customize the presentation of the site to their individual needs, such as enlarging the text, or increasing the visual contrast. This tutorial will show you how create a page for the Infusion UI Options component.

These are the basic steps to create a UI Options page for your site:

Step 1: Prepare your page
Step 2: Add dependencies to the page
Step 3: Write a script to create the UI Options component
One last thing!

The rest of this tutorial will explain each of these steps in detail.

Step 1: Prepare your page

The UI Options component includes templates for its user interface, so you do not need to actually create any HTML if you're happy with the defaults. For the full-page version of UI Options, all you need to do is create an HTML page that has:

one identifiable <div> where the UI Options markup will be inserted
a <div> where the Table of Contents will be displayed (UI Options allows users to request a table of contents be displayed on each page; see the UI Enhancer tutorial for more information about this).

You might also choose to add a heading to the page. This all might look as shown below:

<body>
    <!-- This div should be placed where the Table of Contents is to be displayed -->
    <div class="flc-toc-tocContainer"> </div>

    <h1>Customize Your Presentation Settings</h1>

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

</body>

Note that we've put an ID on the <div>. This ID will be used to tell UI Options exactly which element to use as the main container for all of its markup. You can use any kind of CSS-based selector (e.g. a classname), so long as you are sure it will uniquely identify one and only one element.

If you open this page in your browser, you'll only see the header, since UI Options isn't present on the page yet:

Step 2: Add dependencies to the page

UI Options depends upon Fluid Skinning System (FSS) and the Infusion Framework, so you will need to add to your pages dependencies for

the FSS CSS files,
the UI Options own CSS files, and
the main Infusion JavaScript file, InfusionAll.js (or MyInfusion.js if you've created a custom build).

In the header of the file, link to the FSS CSS files with <link> tags (you'll likely have to adjust the paths to reflect where you've saved the Infusion package).

<!-- Required CSS files -->
<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="components/uiOptions/css/fss/fss-theme-bw-uio.css" />
<link rel="stylesheet" type="text/css" href="components/uiOptions/css/fss/fss-theme-wb-uio.css" />
<link rel="stylesheet" type="text/css" href="components/uiOptions/css/fss/fss-theme-by-uio.css" />
<link rel="stylesheet" type="text/css" href="components/uiOptions/css/fss/fss-theme-yb-uio.css" />
<link rel="stylesheet" type="text/css" href="components/uiOptions/css/fss/fss-text-uio.css" />

You'll also need the UI Options CSS files specific to the Full Page UI Options:

<link rel="stylesheet" type="text/css" href="components/uiOptions/css/UIOptions.css" />
<link rel="stylesheet" type="text/css" href="components/uiOptions/css/FullUIOptions.css" />
<link rel="stylesheet" type="text/css" href="components/uiOptions/css/FullNoPreviewUIOptions.css" />

We'll use the <script> tag to link to the Infusion library:

<!-- The Infusion Library -->
<script type="text/javascript" src="InfusionAll.js"></script>

Note that the InfusionAll.js (or MyInfusion.js) file is a concatenation of all of the JavaScript files, and will be minified (i.e. all of the whitespace removed) if you've downloaded the minified version. If so, it might be difficult to debug with. If you're using the source distribution and you want to be able to debug the code, you might want to include each of the required files individually. To do this: Instead of including InfusionAll.js (or MyInfusion.js) you would include the following files:

<!-- 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 -->

But remember that all of these individual files are not necessary to make it work - the InfusionAll.js file has everything you need.

Step 3: Write a script to create the UI Options component

The simplest way to add the UI Options component to your page is using a <script> tag near the top of the page. We suggest placing it right after the UI Options markup created in Step 1.

<body>
    <!-- UI Options mark-up here -->

    <script type="text/javascript">
        $(document).ready(function () {
            // All of our code will go here
        });
    </script>

    <!-- the rest of your page here -->
</body>

First, we need to add the UI Enhancer component to the page.

As discussed in the UI Enhancer tutorial, we need to add the UI Enhancer to every page on the site, including the UI Options page itself:

<script type="text/javascript">
    $(document).ready(function () {    // Instantiate the UI Enhancer component, specifying the table of contents' template URL
        fluid.pageEnhancer({
            tocTemplate: "<path to your copy of Infusion>/components/tableOfContents/html/TableOfContents.html"
        });
    });
</script>

Finally, we instantiate the UI Options component itself. We do this by calling the creator function, which takes two arguments:

the selector of the container for the component, and
an options object for configuring the component.

The selector for our UI Options will be the ID of the <div> we created in Step 1.

We will use the options to tell the component about two things:

where it's living in relation to the HTML templates included in Infusion: the prefix option
where to redirect when the Cancel button is pressed: an onCancel listener in the uiOptions subcomponent

<script type="text/javascript">
    // Instantiate the UI Enhancer component, specifying the table of contents' template URL
    fluid.pageEnhancer({
        tocTemplate: "<path to your copy of Infusion>/components/tableOfContents/html/TableOfContents.html"
    });                

    // Instantiate the UI Options component
    fluid.uiOptions.fullNoPreview("#myUIOptions", {
        // Tell UIOptions where to find all the templates, relative to this file
        prefix: "<path to your copy of Infusion>/components/uiOptions/html/",

        // Tell UIOptions where to redirect to if the user cancels the operation
        uiOptions: {
            options: {
                listeners: {
                    onCancel: function(){
                        window.location = "<the URL of the page to return to>";
                    }
                }
            }
        }
    });
</script>

Now, when you load your page in your browser, you will see the UI Options controls:

Congratulations!
UI Options is now fully functional on your page. If you adjust the controls and click "Save and Apply," your changes will be applied to the page. If you've also added the UI Enhancer to the other pages of your site, those pages will also be transformed.

One last thing!

Don't forget to add a link to the the UI Options page to your site – somewhere easy-to-find, such as your site's header or footer.