Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

...

Table of Content Zone
locationtop
typelist

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

Include Page
_tutorial setup
_tutorial setup

Anchor
step1
step1

Step 1: Prepare your page

1a: The Sliding Panel

The UI Options component includes HTML templates for all the controls, so you don't need to create any HTML for them. You only need to add a small amount of markup to the top of your page to tell UI Options where to render itself.

Add the following markup as the first thing within your <body> tag:

Code Block
languagexml
linenumberstrue
<div class="flc-prefsEditor-separatedPanel fl-prefsEditor-separatedPanel">
    <!-- This is the div that will contain the Preference Editor component -->
    <div class="flc-slidingPanel-panel flc-prefsEditor-iframe"></div>
    <!-- This div is for the sliding panel that shows and hides the Preference Editor controls -->
    <div class="fl-panelBar">
        <span class="fl-prefsEditor-buttons">
            <button id="reset" class="flc-prefsEditor-reset fl-prefsEditor-reset"><span class="fl-icon-undo"></span> Reset</button>
            <button id="show-hide" class="flc-slidingPanel-toggleButton fl-prefsEditor-showHide"> Show/Hide</button>
        </span>
    </div>
</div>

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

  1. a <div> where an iframe will be inserted, containing the Fat Panel UI Options controls (line 3), and
  2. a <div> where the sliding panel and button will be created (lines 5-10).

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

1b: The Table of Contents

One of the UI Options controls allows users to add a Table Of Contents to the top of the page. You need to add a placeholder <div> to your page for the Table Of Contents. It should have a class of "flc-toc-tocContainer" like this:

Code Block
languagexml
<div class="flc-toc-tocContainer"> </div>

Where exactly on your page you put this <div> is up to you, but it will depend on the exact layout of your page. It should be pretty close to the top, so that it's easily visible and accessible quickly for keyboard-only users. You can, of course, add additional classes of your own to style the Table Of Contents to fit in with the look of your site.

Step 2: Add dependencies to the page

Include Page
_UIO tutorials adding dependencies 1
nopaneltrue
_UIO tutorials adding dependencies 1
nopaneltrue

We'll also need the UI Options CSS files:

Code Block
html
html
<link rel="stylesheet" type="text/css" href="lib/infusion/framework/preferences/css/PrefsEditor.css" />
<link rel="stylesheet" type="text/css" href="lib/infusion/framework/preferences/css/SeparatedPanelPrefsEditor.css" />

Include Page
_UIO tutorials adding dependencies 2nopaneltrue
_UIO tutorials adding dependencies 2
nopaneltrue

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.

Anchor
step3
step3

Step 3: Add 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 before the UI Options markup created in Step 1.

Add the script block as shown below:

Code Block
linenumberstrue
<body>
    <script type="text/javascript">
    $(document).ready(function () {
        fluid.uiOptions.prefsEditor(".flc-prefsEditor-separatedPanel", {
            tocTemplate: "lib/infusion/components/tableOfContents/html/TableOfContents.html",
            templatePrefix: "lib/infusion/framework/preferences/html/",
            messagePrefix: "lib/infusion/framework/preferences/messages/"
        });
    })
    </script>

    <div class="flc-prefsEditor-separatedPanel fl-prefsEditor-separatedPanel">
        ...
    </div>

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

This script calls the fluid.uiOptions.prefsEditor() function to create the component. The function takes two arguments:

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

The selector for our UI Options will be the classname of the <div> we created in Step 1. In this markup, the selector is ".flc-prefsEditor-separatedPanel", on line 11 in the code shown above.

The options tell the component about two things:

  • where to find the UI Options HTML templates included in Infusion: the templatePrefix option, and
  • where to find the message bundles, the strings that will be used in the interface: the messagePrefix option.

In the code above, the messagePrefix option is referencing the default strings provided by the component. If you need to translate the interface into a different language, see Tutorial - Localizing UI Options.

 

Panel
bgColor#c0D9aD

Congratulations!
UI Options is now fully functional on your page. Now, when you load your page in your browser and click on the "Show Display Preferences" button, you will see the UI Options controls, as shon in the image below. If you adjust the controls, you will see your changes being applied to the page.