Work in Progress
This is a working space for creating documentation on integrating UI Options for end users who are not traditional "developers". The intent is to create and refine this documentation so it can be integrated into the official Infusion documentation.
Please leave feedback in the comments section, or send email to: jhung (at) ocadu.ca
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.
- On Windows:
- Launch Powershell: Go to Start, then "Run". Type "
powershell
" into the run text field and press Enter. - In the Powershell window, change directories to your project by typing "
cd ~\Desktop\my-project\temp
" (without the quotes) and pressing Enter.
- Launch Powershell: Go to Start, then "Run". Type "
- On Mac:
- Launch Terminal: Go to Spotlight Search (the magnifying glass in the top-right corner), search for "
Terminal
", and then press Enter. - In the Terminal window, change directories to your project by typing "
cd ~/Desktop/my-project/temp
" (without the quotes) and pressing Enter.
- Launch Terminal: Go to Spotlight Search (the magnifying glass in the top-right corner), search for "
- On Windows:
- Install grunt by typing in the command line "
npm install -g grunt-cli
"- 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.
- On MacOS, if you get an "
- 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 callednode_modules
will be created as a result. - Using the command line, change directory into the infusion directory that's been created within
node_modules
.- On Windows type: "
cd node_modules\infusion
" (without quotes) and press Enter. - On Mac type: "
cd node_modules/infusion
" (without quotes) and press Enter.
- On Windows type: "
- 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/components/tableOfContents/html/TableOfContents.html", terms: { templatePrefix: "infusion/framework/preferences/html", messagePrefix: "infusion/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/components/tableOfContents/html/TableOfContents.html", terms: { templatePrefix: "infusion/framework/preferences/html", messagePrefix: "infusion/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
This section is in-complete.
- Inverting contrast themes
- em, rem, and pixels
- Structure
- Dealing with images and contrast styles
- Focus and hover styling