A Preferences Editor allows users to edit personal preferences that can transform the presentation of the user interface and content resources so that they are personalized to the individual user's needs. This tutorial will walk you through the process of adding a "Separated Panel" Preferences Editor to the top of your website pages.

This tutorial assumes that:

• you are already familiar with HTML, JavaScript and CSS, as well as at least some familiarity with Grunt and node.js.
• you are reasonably familiar with what the Infusion Preferences Editor is and does, and
• now you just want to know how to add it to your website.

Setup: Download the Infusion library and create a custom build

1. Get the current source code from github as a ZIP file: https://github.com/fluid-project/infusion/archive/master.zip
2. Unpack the zip file you just downloaded and cd into the "infusion-master" folder that results.
3. Build a single JS file with only the code you'll need using the following command line:
   grunt custom --source=true --include="preferences"
4. The grunt command will create a zip file in the products folder. Unzip that file and move the resulting infusion folder somewhere convenient for your development purposes, likely in a lib folder in your site hierarchy.

This infusion will include a single file containing all of the JavaScript you need: infusion-custom.js. You will link to this file in the headers of your HTML files.

Step 1: Add necessary files to headers

You will need to add the infusion-custom.js file and a number of CSS files to the headers of your website.

In the header of your file(s) or in the code that produces the headers, add the following lines:

<!-- CSS files required by Preferences Editor -->
<link rel="stylesheet" type="text/css" media="all" href="<path to where you put infusion>/infusion/framework/fss/css/fss-reset-global.css" />
<link rel="stylesheet" type="text/css" media="all" href="<path to where you put infusion>/infusion/framework/fss/css/fss-base-global.css" />
<link rel="stylesheet" type="text/css" media="all" href="<path to where you put infusion>/infusion/framework/fss/css/fss-layout.css" />
<link rel="stylesheet" type="text/css" media="all" href="<path to where you put infusion>/infusion/framework/fss/css/fss-text.css" />
<link rel="stylesheet" type="text/css" href="<path to where you put infusion>/infusion/framework/preferences/css/fss/fss-theme-bw-prefsEditor.css" />
<link rel="stylesheet" type="text/css" href="<path to where you put infusion>/infusion/framework/preferences/css/fss/fss-theme-wb-prefsEditor.css" />
<link rel="stylesheet" type="text/css" href="<path to where you put infusion>/infusion/framework/preferences/css/fss/fss-theme-by-prefsEditor.css" />
<link rel="stylesheet" type="text/css" href="<path to where you put infusion>/infusion/framework/preferences/css/fss/fss-theme-yb-prefsEditor.css" />
<link rel="stylesheet" type="text/css" href="<path to where you put infusion>/infusion/framework/preferences/css/fss/fss-theme-lgdg-prefsEditor.css" />
<link rel="stylesheet" type="text/css" href="<path to where you put infusion>/infusion/framework/preferences/css/fss/fss-text-prefsEditor.css" />
<link rel="stylesheet" type="text/css" href="<path to where you put infusion>/infusion/lib/jquery/ui/css/fl-theme-bw/bw.css" />
<link rel="stylesheet" type="text/css" href="<path to where you put infusion>/infusion/lib/jquery/ui/css/fl-theme-wb/wb.css" />
<link rel="stylesheet" type="text/css" href="<path to where you put infusion>/infusion/lib/jquery/ui/css/fl-theme-by/by.css" />
<link rel="stylesheet" type="text/css" href="<path to where you put infusion>/infusion/lib/jquery/ui/css/fl-theme-yb/yb.css" />    
<link rel="stylesheet" type="text/css" href="<path to where you put infusion>/infusion/lib/jquery/ui/css/fl-theme-lgdg/lgdg.css" />    
<link rel="stylesheet" type="text/css" href="<path to where you put infusion>/infusion/framework/preferences/css/SeparatedPanelPrefsEditor.css" />

<!-- Infusion JavaScript library containing Preferences Framework code -->
<script type="text/javascript" src="<path to where you put infusion>/infusion/infusion-custom.js"></script>

In the snippet above, the phrase <path to where you put infusion> should be replaced by the relative path to the Infusion folder you unpacked in the setup, or a CMS-based command for generating such a path.

Step 2: Add the template HTML to your pages

2a: The panel template

The Preferences Editor will render itself using a section of HTML that you add to the top of your pages. The template provided below should appear on every page, near the top of the body. If you are using a CMS that produces a consistent header or banner, you should add this markup using that functionality. Use the HTML below exactly as it appears:

<!-- begin markup for Prefs Editor Panel -->
<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>
<!-- end markup for Prefs Editor Panel -->

2b: The table of contents

One of the Preference Editor 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:

<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 3: Create the JavaScript that will instantiate the Preferences Editor

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

Add the script block as shown below:

var prefsEditor = fluid.prefs.create(".flc-prefsEditor-separatedPanel", {
    build: {
        gradeNames: [
            "fluid.prefs.auxSchema.starter"
        ],
        auxiliarySchema: {
            templatePrefix: "<path to where you put infusion>/infusion/framework/preferences/html/", 
            messagePrefix: "<path to where you put infusion>/infusion/framework/preferences/messages/",
            tableOfContents: {
                enactor: {
                    tocTemplate: "<path to where you put infusion>/infusion/components/tableOfContents/html/TableOfContents.html"
                }
            }
        }
    }
});

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

The selector for our UI Options will be the classname of the <div> we created in Step 2. In this markup, the selector is ".flc-prefsEditor-separatedPanel". The options argument is a JavaScript object that contains a single property: build. This property provides instructions to the Preferences Framework for building the preferences editor. The properties are:

• gradeNames: This is  a configuration parameter that will tell the Preferences Editor to use the 'starter set' of controls provided with the Framework.
• auxiliarySchema: the object contains information about the location of the Infusion files that the Preference Editor needs to use.
  
  • templatePrefix: where to find the Preference Editor HTML templates included in Infusion
  • messagePrefix: where to find the message bundles – the strings that will be used in the interface
  • tableOfContents: where to find the template for the table of contents

In the code above, the messagePrefix option is referencing the default English strings provided by the component. If you need to translate the interface into a different language, see Localization in the Preferences Framework.