Installing and Getting Started with UI Options

Deprecated documentation

This documentation has been deprecated and is not up to date with the current code base.

For the most up to date documentation for UI Options, see "Setting up User Interface Options" on the Infusion Documentation website.

Overview of Steps

Part 1: Preparing

Prepare your workspace - know where your project is going to be. In this example we will be using Desktop/my-project/
Install node.js - this gives you access to npm which is a repository for Open Source projects and libraries. This is how we will get the latest UI Options.
Install grunt

Part 2: Getting and Building Infusion

Get Infusion via npm
Build Infusion using npm and grunt
Copy the built Infusion libraries to your project
Delete unneeded files

Part 3: Integrating UI Options into Your Project

Add the UIO HTML snippets to your project's HTML pages
Add the UIO Javascript snippets to your project's HTML pages

Part 4: Tweaking and Customizing UI Options

Tweaking your site's styling and structure to work with UI Options

Part 1: Preparing

Before beginning, know where your project files will reside. We will build Infusion (which contains UI Options) and copy its files to your project directory.
Install node.js by following the instructions on their website. node.js will give you access to npm which is a repository for Open Source projects and libraries. This is how we will get Infusion and the latest UI Options.
In your project directory, create a sub-directory called "temp". We will use this to hold intermediate files which can be deleted once Infusion and UI Options is built.
Now open a command line and change directories so you are located in the temp sub-directory in your project directory.
1. On Windows:
  1. Launch Powershell: Go to Start, then "Run". Type "powershell" into the run text field and press Enter.
  2. In the Powershell window, change directories to your project by typing "cd ~\Desktop\my-project\temp" (without the quotes) and pressing Enter.
2. On Mac:
  1. Launch Terminal: Go to Spotlight Search (the magnifying glass in the top-right corner), search for "Terminal", and then press Enter.
  2. In the Terminal window, change directories to your project by typing "cd ~/Desktop/my-project/temp" (without the quotes) and pressing Enter.
Install grunt by typing in the command line "npm install -g grunt-cli"
1. On MacOS, if you get an "Error: EACCESS: Permission denied..." message, you may have to run "sudo npm install -g grunt-cli" instead. You will have to enter your computer password to proceed with installing grunt.
You are now ready to proceed to Part 2.

Sample Mac OS Terminal:

mkdir ~/Desktop/my-project/temp
cd ~/Desktop/my-project/temp
sudo npm install -g grunt-cli

Sample Windows Poweshell:

md ~\Desktop\my-project\temp
cd ~\Desktop\my-project\temp
npm install -g grunt-cli

Part 2: Getting and Building Infusion

Continuing from Part 1.

Get Infusion by typing "npm install infusion" in the command line and pressing Enter. The process will run and a new directory called node_modules will be created as a result.
Using the command line, change directory into the infusion directory that's been created within node_modules.
1. On Windows type: "cd node_modules\infusion" (without quotes) and press Enter.
2. On Mac type: "cd node_modules/infusion" (without quotes) and press Enter.
Now build Infusion by typing "npm install" (without quotes) and press Enter. Once that is done, type "grunt" without quotes and press Enter. This will create a "products" directory in the Infusion directory.
Within the my-project/temp/node_modules/infusion/products directory, there is now a ZIP file called "infusion-all-2.0.0.zip" (the exact filename may be a little different depending on the release of Infusion available at the time you download it). Unzip this file using your preferred Unzipping program.
Now copy (or move) the resulting "infusion" directory into your project's root directory.

Sample Mac OS Terminal:

npm install infusion
cd node_modules/infusion/
npm install
grunt
cd products
unzip infusion-all-2.0.0.zip
mv infusion ~/Desktop/my-project/

Sample Windows Powershell:

npm install infusion
cd node_modules\infusion\
npm install
grunt
cd products
Expand-Archive infusion-all-2.0.0.zip .
move infusion\ ~\Desktop\my-project\

At this point your project directory should look something like this:

my-project/
     |- temp/
     |    |- node_modules/
     |         |- ...
     |         |- infusion/
     |               |- ...
     |               |- products/
     |               |- ...
     |- infusion/

You can now delete the directory "temp" contained inside your project directory. It's no longer needed.

Part 3: Integrating UI Options into Your Project

Now that Infusion has been built and copied into your project, you can now add UI Options into your project.

Adding 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 webpage to tell UI Options where to render itself.

As an example, let's start with a simple HTML page:

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>My Project</title>
    </head>
    <body>
        <h1>This is my project</h1>
        <p>This is a paragraph.</p>
    </body>
</html>

Add the following markup at the very beginning within your <body> tag to your page html:

<!-- UI Options Sliding 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>

So our example will look like this now:

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>My Project</title>
    </head>
    <body>
        <!-- UI Options Sliding 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>
        <h1>This is my project</h1>
        <p>This is a paragraph.</p>
    </body>
</html>

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:

<div class="flc-toc-tocContainer"> </div>

Where exactly on your page you put this 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.

The example will now look like this with the table of contents container added:

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>My Project</title>
    </head>
    <body>
        <!-- UI Options Sliding 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>

        <!-- Table of Contents -->
        <div class="flc-toc-tocContainer"> </div>

        <h1>This is my project</h1>
        <p>This is a paragraph.</p>
    </body>
</html>

Add CSS and Javascript Links

In the <head> of your HTML file, you now need to link to the UI Options CSS and Javascript. To do this, the following should be added to <head>:

<!-- UI Options CSS -->
<link rel="stylesheet" type="text/css" href="infusion/src/lib/normalize/css/normalize.css" />
<link rel="stylesheet" type="text/css" href="infusion/src/framework/core/css/fluid.css" />
<link rel="stylesheet" type="text/css" href="infusion/src/framework/preferences/css/Enactors.css" />
<link rel="stylesheet" type="text/css" href="infusion/src/framework/preferences/css/PrefsEditor.css" />
<link rel="stylesheet" type="text/css" href="infusion/src/framework/preferences/css/SeparatedPanelPrefsEditor.css" />'

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

Note: In the above snippet, it assumes the Infusion directory is sibling to the location of the HTML file. You may have to adjust the path in the <link> and <script> elements to match your particular directory structure.

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.

Our example should now look like this:

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>My Project</title>
		<!-- UI Options CSS -->
        <link rel="stylesheet" type="text/css" href="infusion/src/lib/normalize/css/normalize.css" />
        <link rel="stylesheet" type="text/css" href="infusion/src/framework/core/css/fluid.css" />
        <link rel="stylesheet" type="text/css" href="infusion/src/framework/preferences/css/Enactors.css" />
        <link rel="stylesheet" type="text/css" href="infusion/src/framework/preferences/css/PrefsEditor.css" />
        <link rel="stylesheet" type="text/css" href="infusion/src/framework/preferences/css/SeparatedPanelPrefsEditor.css" />'

        <!-- The Infusion Library -->
        <script type="text/javascript" src="infusion/infusion-all.js"></script>
    </head>
    <body>
        <!-- UI Options Sliding 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>

        <!-- Table of Contents -->
        <div class="flc-toc-tocContainer"> </div>

        <h1>This is my project</h1>
        <p>This is a paragraph.</p>
    </body>
</html>

Initialize the UI Options JavaScript

We will now need to initialize UI Options. To do this you will need to add the following <script> block before the closing </body> tag in your HTML file.

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

So in our example, the HTML should now look like this:

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>My Project</title>
		<!-- UI Options CSS -->
        <link rel="stylesheet" type="text/css" href="infusion/src/lib/normalize/css/normalize.css" />
        <link rel="stylesheet" type="text/css" href="infusion/src/framework/core/css/fluid.css" />
        <link rel="stylesheet" type="text/css" href="infusion/src/framework/preferences/css/Enactors.css" />
        <link rel="stylesheet" type="text/css" href="infusion/src/framework/preferences/css/PrefsEditor.css" />
        <link rel="stylesheet" type="text/css" href="infusion/src/framework/preferences/css/SeparatedPanelPrefsEditor.css" />'

        <!-- The Infusion Library -->
        <script type="text/javascript" src="infusion/infusion-all.js"></script>
    </head>
    <body>
        <!-- UI Options Sliding 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>

        <!-- Table of Contents -->
        <div class="flc-toc-tocContainer"> </div>

        <h1>This is my project</h1>
        <p>This is a paragraph.</p>

		<!-- Initialize UI Options JavaScript -->
        <script type="text/javascript">
            $(document).ready(function () {
                fluid.uiOptions.prefsEditor(".flc-prefsEditor-separatedPanel", {
                    tocTemplate: "infusion/src/components/tableOfContents/html/TableOfContents.html",
                    terms: {
                        templatePrefix: "infusion/src/framework/preferences/html",
                        messagePrefix: "infusion/src/framework/preferences/messages"
                    }
                });
            })
        </script>
	</body>
</html>

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. If you adjust the controls, you will see the effects being applied to the page.

Part 4: Customizing and Optimizing Your Site for UI Options

To get the most out of UI Options, see this guide "Working with UI Options". It is a starting point for customizing and optimizing your site for UI Options, and also addresses some common integration issues.