Documentation for a historical release of Infusion: 1.4
Please view the Infusion Documentation site for the latest documentation, or the Infusion 1.3. Documentation for the previous release.
If you're looking for Fluid Project coordination, design, communication, etc, try the Fluid Project Wiki.

Tutorial - Fat Panel UI Options

Owned by Anastasia Cheetham

Last updated: May 29, 2013Version comment

6 min read

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

If you are working with the latest code from the
gitHub repository, please contact the
mailing list for updated advice, or ask in the IRC channel.

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.

a screenshot of the fat-panel UI Options interface

The Fat Panel version of UI Options displays the interface controls in a collapsible sliding panel at the top of a page. This tutorial will walk you through the process of setting up the fat panel 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 add UI Options and UI Enhancer to your application:

Setup: Download and install the Infusion library
Step 1: Prepare your page
Step 2: Add dependencies to the page
Step 3: Modify the iframe imports, if necessary
Step 4: Write a script to create the UI Options component

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

Setup: Download and install the Infusion library

Use the Infusion Builder to create a custom Infusion package containing the components you want:
- http://builder.fluidproject.org/
  You only need to select the "Minified" package, but if you want to actually look at the code, you should select "Source" in the Download Options.
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.

The folder will contain a single file containing all of the JavaScript you need: MyInfusion.js. You will link to this file in the headers of your HTML files.

Step 1: Prepare your page

The Fat Panel UI Options component includes a template for the controls, so you do not need to actually create any HTML. You only need to add a small amount of markup to the top of your page:

<div class="flc-uiOptions-fatPanel fl-uiOptions-fatPanel">
    <!-- This is the div that will contain the UI Options component -->
    <div id="myUIOptions" class="flc-slidingPanel-panel flc-uiOptions-iframe"></div>

    <!-- This div is for the sliding panel that shows and hides the UI Options controls -->
    <div class="fl-panelBar">
        <button class="flc-slidingPanel-toggleButton fl-toggleButton">The show/hide button label will go here</button>
    </div>
</div>

The main <div> in this snippet contains two things:

a <div> where an iframe will be inserted, containing the Fat Panel UI Options controls, and
a <div> where the sliding panel and button will be created.

The elements in this snippet all have particular class names attached to them, and it's important to keep them:

the class names starting with flc- are used to identify the elements to UI Options;
the class names starting wtih fl- are used for visual styling.

If you open this page in your browser now, you'll only see the button in the upper left corner, since we haven't set up the CSS, and UI Options isn't present on the page yet:

Note that it doesn't matter what text you put in the button: The UI Options component will add a label and update it to reflect whether or not the panel is currently open. You can configure the text that the component uses by setting its configuration parameters. (After you've finished the tutorial, check out the instructional demo Fat Panel UI Options - Custom Show-Hide Button for an example of configuring the button text.)

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

Because the Fat Panel version of UI Options uses jQuery tabs, we'll need the jQuery theme files for the high-contrast themes:

<link rel="stylesheet" type="text/css" href="lib/jquery/ui/css/fl-theme-hc/hc.css" />
<link rel="stylesheet" type="text/css" href="lib/jquery/ui/css/fl-theme-hci/hci.css" />
<link rel="stylesheet" type="text/css" href="lib/jquery/ui/css/fl-theme-blackYellow/blackYellow.css" />
<link rel="stylesheet" type="text/css" href="lib/jquery/ui/css/fl-theme-yellowBlack/yellowBlack.css" />

Finally, we'll need the UI Options CSS file specific to the Fat Panel UI Options:

<link rel="stylesheet" type="text/css" href="components/uiOptions/css/FatPanelUIOptions.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.

If you open this page in your browser now, you'll only see that the button has been styled differently: it is in the upper right corner and the font has been changed. You can also see the bar of the sliding panel. The button still doesn't do anything, since we still haven't added the UI Options component to the page.

Step 3: Modify the iframe imports, if necessary

If you are using a build of Infusion, with the InfusionAll.js or MyInfusion.js file, you'll need to modify the header of the <iframe> template to reference the build file instead of the individual files.

The panel at the top of the page loads its content from a separate file: FatPanelUIOptionsFrame.html. By default, this file links to each Infusion JavaScript file separately. You'll need to remove all of the <script> tags linking to individual *.js files and replace them with a single <script> tag linking to the concatenated build file:

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

Step 4: 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>

Because we're applying the Fat Panel UI Options component to page that has its own theme, we need to tell the UI Enhancer the name of that theme by adding another option: the classnameMap. Modify your call to fluid.pageEnhancer as follows:

<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",
        classnameMap: {
            theme: {
                "default": "uio-demo-theme"
            }
        }
    });
});
</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 one thing:

where it's living in relation to the HTML templates included in Infusion: the prefix option

In order to protect the UI Options controls themselves from being modified as users adjust those very controls, UI Options uses an <iframe> to contain the controls themselves. This isolates the controls from the UI Enhancer that is on the main page. As with the templates, we need to tell the <iframe> subcomponent where to find its content.

<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",
        classnameMap: {
            theme: {
                "default": "uio-demo-theme"
            }
        }
    });

    // Start up UI Options
    fluid.uiOptions.fatPanel(".flc-uiOptions-fatPanel", {
        prefix: "<path to your copy of Infusion>/components/uiOptions/html/"
    });
</script>

Now, when you load your page in your browser and click on the "Show Display Preferences" button, you will see the UI Options controls:

Congratulations!
UI Options is now fully functional on your page. If you adjust the controls, you will see your changes being applied to the page.