Merge remote-tracking branch 'jhung/FLUID-5439'

* jhung/FLUID-5439: FLUID-5439: Trying to fix improper formatting of a paragraph. FLUID-5439: Fixed Infusion download links and formatting. FLUID-5439: Fixes for images, paths, and text FLUID-5439: Migrating UIO documentation to Infusion docs from the wiki. FLUID-5439: Migrating UIO tutorial documentation from Infusion 1.4 wiki.
fluid-project · Jul 5, 2017 · fd62e88 · fd62e88
2 parents 306f3b2 + 2c8b766
commit fd62e88
Show file tree

Hide file tree

Showing 20 changed files with 487 additions and 3 deletions.
diff --git a/site-structure.json b/site-structure.json
@@ -194,7 +194,11 @@
                 "sectionName": "User Interface Options",
                 "pages":
                 [
-                    { "pageName": "User Interface Options", "href": "/tutorial-userInterfaceOptions/UserInterfaceOptions.html" }
+                    { "pageName": "Setting Up User Interface Options", "href": "/tutorial-userInterfaceOptions/UserInterfaceOptions.html" },
+                    { "pageName": "Working with User Interface Options", "href": "/tutorial-userInterfaceOptions/WorkingWithUserInterfaceOptions.html"},
+                    { "pageName": "Using Images in Contrast Modes", "href": "/tutorial-userInterfaceOptions/UsingImagesInContrastModes.html"},
+                    { "pageName": "Style Effects and Legibility in Contrast Modes", "href": "/tutorial-userInterfaceOptions/StyleEffectsAndLegibilityInContrastModes.html"},
+                    { "pageName": "CSS 'Content' Property in Contrast Modes", "href": "/tutorial-userInterfaceOptions/ContentPropertyHighContrast.html"}
                 ]
             }
         ]

diff --git a/src/documents/images/tutorial-uio-button-hc.png b/src/documents/images/tutorial-uio-button-hc.png
diff --git a/src/documents/images/tutorial-uio-button-regular.png b/src/documents/images/tutorial-uio-button-regular.png
diff --git a/src/documents/images/tutorial-uio-content-bw.png b/src/documents/images/tutorial-uio-content-bw.png
diff --git a/src/documents/images/tutorial-uio-content-by.png b/src/documents/images/tutorial-uio-content-by.png
diff --git a/src/documents/images/tutorial-uio-content-default.png b/src/documents/images/tutorial-uio-content-default.png
diff --git a/src/documents/images/tutorial-uio-content-lgdg.png b/src/documents/images/tutorial-uio-content-lgdg.png
diff --git a/src/documents/images/tutorial-uio-content-wb.png b/src/documents/images/tutorial-uio-content-wb.png
diff --git a/src/documents/images/tutorial-uio-content-yb.png b/src/documents/images/tutorial-uio-content-yb.png
diff --git a/src/documents/images/tutorial-uio-good-bad-logos.png b/src/documents/images/tutorial-uio-good-bad-logos.png
diff --git a/src/documents/images/tutorial-uio-icon-hc.png b/src/documents/images/tutorial-uio-icon-hc.png
diff --git a/src/documents/images/tutorial-uio-icon-regular.png b/src/documents/images/tutorial-uio-icon-regular.png
diff --git a/src/documents/images/tutorial-uio-lock-pixels.png b/src/documents/images/tutorial-uio-lock-pixels.png
diff --git a/src/documents/images/tutorial-uio-shadow-hc.png b/src/documents/images/tutorial-uio-shadow-hc.png
diff --git a/src/documents/images/tutorial-uio-shadow-regular.png b/src/documents/images/tutorial-uio-shadow-regular.png
diff --git a/src/documents/tutorial-userInterfaceOptions/ContentPropertyHighContrast.md b/src/documents/tutorial-userInterfaceOptions/ContentPropertyHighContrast.md
@@ -0,0 +1,64 @@
+---
+title: CSS "Content" Property in Contrast Modes
+layout: default
+category: Tutorials
+---
+
+The CSS `content` property can be used to add additional content to your webpage using CSS. Often it is used to add a character, symbol, or font icon before or after some content on webpage. For example, it can be used to add vertical bars to separate items on a horizontal navigation list as depicted by the following HTML and CSS snippets.
+
+
+```html
+<nav>
+  <ul class="topnav">
+    <li>Home</li>
+    <li>Browse</li>
+    <li>Shop</li>
+  </ul>
+</nav>
+```
+
+```css
+.topnav {
+  color: #0000ff;
+  list-style: none;
+}
+
+.topnav li {
+  float: left;
+}
+
+.topnav li:after {
+  color: #0000ff;
+  content: "|";
+  padding: 0 2rem;
+}
+```
+
+The above example would look like this:
+![A horizontal navigation list with blue text on grey background.](../images/tutorial-uio-content-default.png)
+
+To style this example, a new colour for `content` should be specified for each contrast. The updated CSS could look like this:
+
+```css
+.fl-theme-yb .topnav li:after {
+  color: #FFFF00; /* yellow for yellow-on-black */
+}
+.fl-theme-wb .topnav li:after {
+  color: #FFFFFF;  /* white for white-on-black */
+}
+.fl-theme-by .topnav li:after,
+.fl-theme-bw .topnav li:after {
+  color: #000000; /* black for black-on-yellow and black-on-white */
+}
+.fl-theme-lgdg .topnav li:after {
+  color: #bdbdbb;  /* light grey for light grey on dark grey */
+}
+```
+
+When properly styled, the `content` value will change according to the contrast theme. Our example would now look like this:
+
+* ![A horizontal navigation list with yellow text on black background.](../images/tutorial-uio-content-yb.png)
+* ![A horizontal navigation list with white text on black background.](../images/tutorial-uio-content-wb.png)
+* ![A horizontal navigation list with black text on white background.](../images/tutorial-uio-content-bw.png)
+* ![A horizontal navigation list with black text on yellow background.](../images/tutorial-uio-content-by.png)
+* ![A horizontal navigation list with light gret text on grey background.](../images/tutorial-uio-content-lgdg.png)
diff --git a/...ments/tutorial-userInterfaceOptions/StyleEffectsAndLegibilityInContrastModes.md b/...ments/tutorial-userInterfaceOptions/StyleEffectsAndLegibilityInContrastModes.md
@@ -0,0 +1,72 @@
+---
+title: Style Effects and Legibility in Contrast Modes
+layout: default
+category: Tutorials
+---
+
+One of the goals of the contrast themes is to provide legibility and clarity for viewers. Shadows on text or other graphics can provide appealing visual effects, but this can adversely affect legibility for some people. When creating styles for contrast modes, it's important to remember to remove such shadows and other graphical effects.
+
+## Improving Clarity - Removing Drop Shadows
+
+```html
+<button class="idi-prefs-button">preferences</button>
+```
+
+```css
+.idi-prefs-button {
+    color: #000000;
+    text-shadow: 0.1rem 0.1rem 0 #FFFFFF;
+    background-color: #E5E5E5;
+    background-image: url("images/preferences.png");
+    background-position: 0.4em 50%;
+    background-repeat: no-repeat;
+    width: 8em;
+}
+.fl-theme-yb .idi-prefs-button {
+    text-shadow: none;
+    border: 0.1rem solid yellow;
+    background-image: url("images/preferences-yellow.png");
+}
+```
+
+This button uses a white drop shadow on the black text to provide an elegant embossed look:
+
+![A button with text label with a shadow effect.](../images/tutorial-uio-shadow-regular.png)
+
+But such a shadow would be inappropriate for a high contrast theme. In this example (the yellow-on-black theme in this case), the text shadow is removed completely:
+
+![A button with a yellow yellow text label on a black background.](../images/tutorial-uio-shadow-hc.png)
+
+## Another Example - Gradients
+
+Gradients are often used for visual effects, as well as giving buttons a 3D effect. The example below shows how to use the UI Options contrast class to improve legibility for contrast modes.
+
+```html
+<button class="search-btn">Search</button>
+```
+
+```css
+.search-btn {    
+  background: rgba(70,140,170,1);
+  background: -moz-linear-gradient(top, rgba(70,140,170,1) 0%, rgba(19,88,118,1) 100%);
+  background: -webkit-gradient(left top, left bottom, color-stop(0%, rgba(70,140,170,1)), color-stop(100%, rgba(19,88,118,1)));
+  background: -webkit-linear-gradient(top, rgba(70,140,170,1) 0%, rgba(19,88,118,1) 100%);
+  background: -ms-linear-gradient(top, rgba(70,140,170,1) 0%, rgba(19,88,118,1) 100%);
+  background: linear-gradient(to bottom, rgba(70,140,170,1) 0%, rgba(19,88,118,1) 100%);
+  border: medium none;
+  box-shadow: 0.1rem 0.1rem 0 #135876 inset, 0.1rem 0.1rem 0 #FFFFFF;
+  color: #FFFFFF;
+}
+.fl-theme-wb .search-btn {
+  background: #FFFFFF;
+  border-color: #000000;
+  color: #000000;
+  box-shadow: none;
+}
+```
+
+In this example, a button was given a gradient effect:
+![Image of a button with white text label on a shaded blue background.](../images/tutorial-uio-button-regular.png)
+
+The CSS for the high-contrast version (in this example, "white-on-black") simply inverts the basic colour scheme to produce a 'button' effect, removing the gradient, shadow, and forcing the background and border colours to conform to the theme colours.
+![Image of a button with black text label on a solid white background.](../images/tutorial-uio-button-hc.png)
diff --git a/src/documents/tutorial-userInterfaceOptions/UserInterfaceOptions.md b/src/documents/tutorial-userInterfaceOptions/UserInterfaceOptions.md
@@ -1,5 +1,5 @@
 ---
-title: User Interface Options
+title: Setting Up User Interface Options
 layout: default
 category: Tutorials
 ---
@@ -37,7 +37,7 @@ The rest of this tutorial will explain each of these steps in detail.
 
 ## Download and install the UI Options library ##
 
-1. [Download the UI Options library](https://github.com/fluid-project/infusion/releases/download/infusion-2.0/infusion-uiOptions-2.0.0-source.zip) (there is also a [minified version UI Options](https://github.com/fluid-project/infusion/releases/download/infusion-2.0/infusion-uiOptions-2.0.0-minified.zip) for deployment purposes).
+1. [Download the UI Options library](https://github.com/fluid-project/infusion/releases/download/v2.0.0/infusion-uiOptions-2.0.0-source.zip) (there is also a [minified version UI Options](https://github.com/fluid-project/infusion/releases/download/v2.0.0/infusion-all-2.0.0-minified.zip) for deployment purposes).
 2. Unzip the contents of the downloaded ZIP file to a location within your project. This will result in a new directory `infusion`. <div class="infusion-docs-note"><strong>Note:</strong> In this guide we will use the directory `my-project/lib/`.</div>
 3. Your `infusion` folder will include a single file containing all of the JavaScript you need (`infusion-uiOptions.js`), HTML templates, CSS files, and other components to get UI Options to work. You will later link to these files in your HTML files.
 4. Now that `infusion` is in your project directory, you can delete the `infusion-uiOptions-2.0.0.zip` (or similar name) from your download directory.
@@ -229,3 +229,5 @@ Here's the complete example from start to finish. This example assumes the Infus
 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 shown in the image below. If you adjust the controls, you will see your changes being applied to the page.
 
 ![Screen shot of UI Options](../images/uio.png "Screen shot of UI Options.")
+
+You may have to adjust your site's styles to work properly with UI Options. The ["Working With User Interface Options"](./WorkingWithUserInterfaceOptions.md) can help you get started.
diff --git a/src/documents/tutorial-userInterfaceOptions/UsingImagesInContrastModes.md b/src/documents/tutorial-userInterfaceOptions/UsingImagesInContrastModes.md
@@ -0,0 +1,161 @@
+---
+title: Using Images in Contrast Modes
+layout: default
+category: Tutorials
+---
+
+The User Interface Options component allows users to easily transform pages into one of several contrast versions. The results of this transformation are much more complete if any logos, images, and other graphics are also converted to match the contrast scheme.
+
+If you are integrating UI Options into your site, we highly recommend you create contrast versions of your site logo, and any other similarly static image. This page is divided into two sections:
+
+1. Creating contrast versions of your graphics using Photoshop (or similar image editing software), and
+2. Using CSS to switch between different contrast versions of the images.
+
+![A logo appearing properly with a yellow-on-black contrast theme](../images/tutorial-uio-good-bad-logos.png)
+
+## Converting Images With Transparency
+
+UI Options provides four high contrast themes:
+
+* yellow (`#FFFF00`) on black (`#000000`)
+* white (`#FFFFFF`) on black (`#000000`)
+* black (`#000000`) on yellow (`#FFFF00`)
+* black (`#000000`) on white (`#FFFFFF`)
+* light grey (`#BDBDBB`) on dark grey (`#555555`)
+
+These themes would require different versions of images and graphics to match. To do this you will need to use image editing software like Photoshop to change the colours of the images to match the different contrast themes.
+
+The simplest images to convert are ones that already have a transparent background. Creating contrast versions involves 'locking' the transparent pixels so they stay transparent and then painting over everything not-transparent with the desired colour.
+
+## Creating Contrast Images in Photoshop
+
+### Step 1 - Lock the transparent pixels
+
+In Photoshop, you can lock the transparent pixels in one of at least two ways:
+
+1. Type the '`/`' key, or
+2. In the "Layers" panel, click the 'lock pixels button (see image below).
+
+![Image of the Photoshop Layers panel with the mouse cursor hovering over the Lock transparent pixels button](../images/tutorial-uio-lock-pixels.png)
+
+### Step 2 - Fill the rest of the image with the desired colour
+
+In Photoshop, there are several ways to fill the image with a single colour:
+
+1. Type `Alt + Delete` on Mac, or `Alt + Backspace` on Windows to fill the image with the current foreground colour, or
+2. Type `Command + Delete` on Mac, or `Command + Backspace` on Windows to fill the image with the current background colour, or
+3. Choose a paintbrush and a foreground colour, and drag the cursor over the image.
+
+### Step 3 - Save the image for the web
+
+* On Mac: Type `Shift + Alt + Command + S`
+* On Windows: Type `Shift + Alt + Ctrl + S`
+
+### Inverting Colours for Quick Black-White and White-Black Images
+
+If you've created a black (or white) image, you can invert the colour to convert it to white (or black) by typing `Command + I` on Mac, or `Ctrl + I` on Windows.
+
+## Using CSS to Switch Web Graphics for Contrast Modes
+
+While web images and graphics are typically implemented using `<img>` tags, using background images instead makes it very simple to substitute a different version of the image when a high contrast theme is used.
+
+### When to Use Background Images and `<img>` Tags
+
+Images on web pages are often implemented by using `<img>` tags. However, the `background` CSS property for images may be advantageous.
+
+To help decide whether to use an `<img>` element or a background image, a good rule of thumb would be to use:
+* `<img>` tags if the graphic is important as content (i.e. a graph, photo, or a diagram).
+* CSS `background` property for graphics that are cosmetic in nature, such as icons and logos.
+
+The advantage of using `background` is that assistive technologies (like screen readers) will ignore them since it is considered as cosmetic. This allows you to declutter and simplify the user experience by not having extraneous content.
+
+<div class="infusion-docs-note"><strong>Note:</strong> UI Options changes the presentation of content by using CSS. Therefore images implemented with <code>&lt;img&gt;</code> HTML elements are not easily modified using CSS. It is possible to achieve a similar contrast effect by using <a href="https://developer.mozilla.org/en/docs/Web/CSS/filter">CSS filters</a>, but the results may not match the contrast mode.</div>
+
+### Example Contrast Image Switching
+The following example shows how CSS can be used to switch background images with contrast versions.
+
+HTML:
+```html
+<a class="site-logo" title="Example Company" href="http://www.example.com">
+    Example Company
+</a>
+```
+
+CSS
+```css
+.site-logo {
+    background-image: url("images/logo.png");
+    background-repeat: no-repeat;
+}
+/* white logo for white-on-black theme */
+.fl-theme-wb .site-logo {
+    color: #fff;
+    background-image: url("images/logo-white.png");
+}
+/* yellow logo for yellow-on-black theme */
+.fl-theme-yb .site-logo {
+    color: #ff0;
+    background-image: url("images/logo-yellow.png");
+}
+/* black logo for black-on-white and black-on-yellow themes */
+.fl-theme-bw .site-logo,
+.fl-theme-by .site-logo {
+    color: #000;
+    background-image: url("images/logo-black.png");
+}
+/* light grey logo for light grey and dark grey theme */
+.fl-theme-lgdg .site-logo {
+    color: #bdbdbb;
+    background-image: url("images/logo-grey.png");
+}
+```
+
+The logo in the above example is implemented as a background image on a link to the site's home page. The contrast images are substituted by using the same selector (i.e. `.site-logo`) prefaced with the theme class (i.e. `.fl-theme-wb`), and specifying only the new image file. All other styles remain the same.
+
+When a user selects a contrast theme using UI Options, the theme class will be added to the `<body>` of the document and the high contrast logo will automatically be loaded.
+
+It's worth noting that the images are implemented using a transparent background so that a single logo can be used for different contrast themes. For example, a black logo on a transparent background can be used for both the black-on-white theme and the black-on-yellow theme.
+
+### Another Example of Contrast Image Switching
+
+The following example shows how icons on navigation links can be changed to contrast versions. The approach here is like the previous example.
+
+### HTML
+
+```html
+<nav>
+  <ul>
+    <li><a href="about" class="about">About</a></li>
+    <li><a href="people" class="people currentPage">People</a></li>
+    <li><a href="news" class="news">News</a></li>
+  </ul>
+</nav>
+```
+
+```css
+.people.currentPage {
+  background-image: url("images/people-white.png");
+  background-position: 0.3em 50%;
+  background-repeat: no-repeat;
+  background-size: auto 75%;
+  padding-left: 2em;
+  background-color: #0076B0;
+  color: #FFFFFF;
+}
+.fl-theme-by .people.currentPage {
+    background-image: url("images/people-yellow.png");
+}
+.fl-theme-yb .idi-people.currentPage,
+.fl-theme-wb .idi-people.currentPage {
+    background-image: url("images/people-black.png");
+}
+.fl-theme-lgdg .idi-people.currentPage {
+    background-image: url("images/people-grey.png");
+}
+```
+
+In this example, the 'current page' tab has an inverted colour scheme. The default colour would appear as shown in the following image:
+![A graphical icon in its default colour of blue on white.](../images/tutorial-uio-icon-regular.png)
+
+The high contrast version of the theme inverts the colour, so in the "black-on-white" theme, for example, the graphic itself should appear white-on-black to keep with the original inverted style:
+![A graphical icon in black on white contrast theme.](../images/tutorial-uio-icon-hc.png)