This tutorial has not yet been re-written to reflect the recent refactoring of the Preferences Framework. Stay tuned...
This tutorial applies to v1.4 of UI Options.
For earlier versions, see
Tutorial - UI Options and UI Enhancer.
The Full Page With Preview version of UI Options displays the interface controls in a separate page and includes a Preview pane that is updated automatically as the user adjusts the controls. This tutorial will walk you through the process of setting up the full page with preview 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:
Tutorial - Page Enhancer
Tutorial - Full Page UI Options
Tutorial - Fat Panel UI Options
Working With A Preferences Editor On Your Site
UI Options Instructional Demos
Full Page UI Options (with Preview)
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:
The rest of this tutorial will explain each of these steps in detail.
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 (with preview) version of UI Options, all you need to do is create an HTML page that has:
<div>where the UI Options markup will be inserted
<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:
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:
In the header of your file, link to the FSS CSS files with
<link> tags (you may have to adjust the paths to reflect where you've saved the Infusion package).
You'll also need the UI Options CSS files specific to the Full Page UI Options with the Preview:
We'll use the
<script> tag to link to the Infusion library:
Note that the
<script>tag near the top of the page. We suggest placing it right before the UI Options markup created in Step 1. Finally, we instantiate the UI Options component itself. We do this by calling the creator function, which takes two arguments:
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:
onCancellistener in the
Now, when you load your page in your browser, you will see the UI Options controls, but there will be no Preview yet. UI Options will work: If you adjust the controls and click "Save and Apply," your changes will be applied to the page. There's just no Preview.
UI Options does not come with a default Preview template – you must provide your own. Your users will be best served if the preview looks somewhat like your site.
The simplest way to use the Preview is through UI Options' default behaviour. Name your Preview template file as follows:
and place it in the same folder as your main UI Options HTML file. If you follow this convention, UI Options will automatically find your Preview template.
The Preview template file will be loaded into an
<iframe>, so it must be a fully valid HTML file, with a header that includes any require CSS, etc. It will be displayed in the right half of the screen, so you may wish to design something that is not overly complex. Your preview should be styled the same was as your site, using the same theme (see the UI Enhancer tutorial for more information). Other than that, your preview can contain whatever you like.
A UI Enhancer will automatically be applied to the page in the preview
<iframe>, so as described in the UI Enhancer tutorial, you need to tell that Enhancer about the theme name and the path to the Table of Contents template:
Now when you load the page, you'll see your Preview template visible in the right half of the screen:
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.