From f6ab6622aab00fe7c2f4c3dc41f786ebbe0f0d73 Mon Sep 17 00:00:00 2001 From: Rogan Creswick Date: Fri, 30 Mar 2012 17:07:02 -0700 Subject: initial revision --- doc/manual_src/Makefile | 10 + doc/manual_src/figures/chrome-adding.png | Bin 0 -> 9348 bytes .../figures/chrome-confirm-add-fiveui.png | Bin 0 -> 13457 bytes doc/manual_src/figures/chrome-file-url.png | Bin 0 -> 20422 bytes doc/manual_src/figures/chrome-install-done.png | Bin 0 -> 28218 bytes doc/manual_src/figures/chrome-menu.png | Bin 0 -> 67244 bytes doc/manual_src/figures/ff-add-on-installer.png | Bin 0 -> 47821 bytes doc/manual_src/figures/ff-add-rule-set.png | Bin 0 -> 47174 bytes doc/manual_src/figures/ff-addon-bar.png | Bin 0 -> 38613 bytes doc/manual_src/figures/ff-heading-highlight.png | Bin 0 -> 46962 bytes doc/manual_src/figures/ff-menu.png | Bin 0 -> 49769 bytes doc/manual_src/figures/trac-aria1.png | Bin 0 -> 68754 bytes doc/manual_src/figures/trac-rule-set.png | Bin 0 -> 74861 bytes doc/manual_src/gettingStarted.md | 236 +++++++++++++++++++++ doc/manual_src/install.md | 85 ++++++++ 15 files changed, 331 insertions(+) create mode 100644 doc/manual_src/Makefile create mode 100644 doc/manual_src/figures/chrome-adding.png create mode 100644 doc/manual_src/figures/chrome-confirm-add-fiveui.png create mode 100644 doc/manual_src/figures/chrome-file-url.png create mode 100644 doc/manual_src/figures/chrome-install-done.png create mode 100644 doc/manual_src/figures/chrome-menu.png create mode 100644 doc/manual_src/figures/ff-add-on-installer.png create mode 100644 doc/manual_src/figures/ff-add-rule-set.png create mode 100644 doc/manual_src/figures/ff-addon-bar.png create mode 100644 doc/manual_src/figures/ff-heading-highlight.png create mode 100644 doc/manual_src/figures/ff-menu.png create mode 100644 doc/manual_src/figures/trac-aria1.png create mode 100644 doc/manual_src/figures/trac-rule-set.png create mode 100644 doc/manual_src/gettingStarted.md create mode 100644 doc/manual_src/install.md (limited to 'doc/manual_src') diff --git a/doc/manual_src/Makefile b/doc/manual_src/Makefile new file mode 100644 index 0000000..76fdbda --- /dev/null +++ b/doc/manual_src/Makefile @@ -0,0 +1,10 @@ + +DOCS := $(patsubst %.md,%.html,$(wildcard *.md)) + +all: $(DOCS) + +clean: + $(RM) $(DOCS) + +%.html: %.md + pandoc $< -o $@ -s --highlight-style=kate diff --git a/doc/manual_src/figures/chrome-adding.png b/doc/manual_src/figures/chrome-adding.png new file mode 100644 index 0000000..6b25ddd Binary files /dev/null and b/doc/manual_src/figures/chrome-adding.png differ diff --git a/doc/manual_src/figures/chrome-confirm-add-fiveui.png b/doc/manual_src/figures/chrome-confirm-add-fiveui.png new file mode 100644 index 0000000..fa1e29c Binary files /dev/null and b/doc/manual_src/figures/chrome-confirm-add-fiveui.png differ diff --git a/doc/manual_src/figures/chrome-file-url.png b/doc/manual_src/figures/chrome-file-url.png new file mode 100644 index 0000000..4cb7ee3 Binary files /dev/null and b/doc/manual_src/figures/chrome-file-url.png differ diff --git a/doc/manual_src/figures/chrome-install-done.png b/doc/manual_src/figures/chrome-install-done.png new file mode 100644 index 0000000..d1774ef Binary files /dev/null and b/doc/manual_src/figures/chrome-install-done.png differ diff --git a/doc/manual_src/figures/chrome-menu.png b/doc/manual_src/figures/chrome-menu.png new file mode 100644 index 0000000..9596abd Binary files /dev/null and b/doc/manual_src/figures/chrome-menu.png differ diff --git a/doc/manual_src/figures/ff-add-on-installer.png b/doc/manual_src/figures/ff-add-on-installer.png new file mode 100644 index 0000000..ade0fe2 Binary files /dev/null and b/doc/manual_src/figures/ff-add-on-installer.png differ diff --git a/doc/manual_src/figures/ff-add-rule-set.png b/doc/manual_src/figures/ff-add-rule-set.png new file mode 100644 index 0000000..fd1586c Binary files /dev/null and b/doc/manual_src/figures/ff-add-rule-set.png differ diff --git a/doc/manual_src/figures/ff-addon-bar.png b/doc/manual_src/figures/ff-addon-bar.png new file mode 100644 index 0000000..67f08cc Binary files /dev/null and b/doc/manual_src/figures/ff-addon-bar.png differ diff --git a/doc/manual_src/figures/ff-heading-highlight.png b/doc/manual_src/figures/ff-heading-highlight.png new file mode 100644 index 0000000..0c64937 Binary files /dev/null and b/doc/manual_src/figures/ff-heading-highlight.png differ diff --git a/doc/manual_src/figures/ff-menu.png b/doc/manual_src/figures/ff-menu.png new file mode 100644 index 0000000..f60d822 Binary files /dev/null and b/doc/manual_src/figures/ff-menu.png differ diff --git a/doc/manual_src/figures/trac-aria1.png b/doc/manual_src/figures/trac-aria1.png new file mode 100644 index 0000000..d8cc0a6 Binary files /dev/null and b/doc/manual_src/figures/trac-aria1.png differ diff --git a/doc/manual_src/figures/trac-rule-set.png b/doc/manual_src/figures/trac-rule-set.png new file mode 100644 index 0000000..58de6af Binary files /dev/null and b/doc/manual_src/figures/trac-rule-set.png differ diff --git a/doc/manual_src/gettingStarted.md b/doc/manual_src/gettingStarted.md new file mode 100644 index 0000000..8eb49d4 --- /dev/null +++ b/doc/manual_src/gettingStarted.md @@ -0,0 +1,236 @@ +% Getting Started with FiveUI + +# Configuring FiveUI + +Once FiveUI has been installed, some initial configuration will need to be done +to make the extension useful. + +The options page allows the user to configure `URL Patterns` that will apply +when the browser is navigating to new URLs, and `Rule Sets` which categorize +user interface guidelines into named groups. + +## Options in Chrome + +The options page in `Chrome` can be accessed either through the +options link on the extensions page, or through the options item on +the context menu off of the FiveUI button (accessed by right-clicking +on the FiveUI button). + +## Options in FireFox + +The options page in `FireFox` can be accessed via the FiveUI gear widget, which +should be added in addition to the FiveUI widget when the addon is installed. +Once clicked, a new tab should appear which serves as the options interface for +the addon. + +The FiveUI Widgets are initially placed on the Firefox `Add-on bar`, +as shown in the figure. + +![FiveUI Widgets in the Firefox Add-on Bar.](figures/ff-addon-bar.png) + +# The Options Page + +The options page allows the user to configure `URL Patterns` that will apply +when the browser is navigating to new URLs, and `Rule Sets` which categorize +user interface guidelines into named groups. As it's required that one or more +`Rule Sets` already exist to create a `URL Pattern`, let's start with the `Rule +Sets` tab. + +## Rule Sets + +`Rule Sets` can be managed by clicking on the `Rule Sets` tab on the left-hand +side of the options page. + +`Rule Sets` in FiveUi are specified as a json-like object that +contains javascript functions for the rule implementations. Each +`Rule Set` contains a **name**, **description** and list of zero or +more **rules**. The following snippet exhibits the minimal definition +for a `Rule Set`, providing only the **name** and **description** +fields, along with an empty set of **rules**. + +```javascript +{ "name": "Empty Rules" +, "description": "An example of an empty rule set" +, "rules": [] +} +``` + +### Rules + +The elements of the **rules** array in the `Rule Set` are also represented as +json objects. A minimal rule consists of three fields: **name**, +**description** and **rule**. While **name** and **description** are just +strings, like the definition of a `Rule Set`, the **rule** field is a javascript +function. + +The definition of the **rule** function consists of a single javascript function +that expects no arguments and returns no value. The rule will be invoked with +no special context, and it is expected to perform its validation based on uses of +the `FiveUI prelude`. Rules are able to report problems to the in-page FivUI +interface by invoking the *report* function. + +As a simple example, the following rule will log an error for each header tag +that contains no text: + +```javascript +{ "name": "Disallow Empty Headers" +, "description": "Heading elements should contain text" +, "rule": function() { + fiveui.query(':header').each(function(ix, elt) { + if($(elt).text() == '') { + report('Heading does not contain text', elt); + } + }); + } +} +``` + +### Creating a `Rule Set` + +Reusing the previous example and the skeleton of the first, we can create a +simple `Rule Set` that applies the empty header rule: + +* Begin by copying this code block, so that it will be available to the `Rule + Set` editor later. + +```javascript +{ "name": "Header Rule Set" +, "description": "Simple rules about HTML headers." +, "rules": + [ { "name": "Disallow Empty Headers" + , "description": "Heading elements should contain text." + , "rule": function() { + fiveui.query(':header').each(function(ix, elt) { + if($(elt).text() == '') { + report('Heading does not contain text', elt); + } + }); + } + } + ] +} +``` + +* Next, open the options page for the FiveUI extension. +* Navigate to the `Rule Sets` preferences tab, by clicking the `Rule Sets` link + on the left-hand side of the page. +* Click the `Add` button. +* Paste in the contents of the example Rule Set into the text area that appears. + FiveUI should highlight the syntax of the rule. + +![FiveUI uses a rich Javascript editor to highlight rule sets.](figures/ff-add-rule-set.png) + +* Click the `Save` button. +* An entry in the list above the `Add` button should appear, describing the rule + that was added in the previous steps. + +## URL Patterns + +`URL Patterns` can be managed by first clicking the `URL Patterns` tab on the +left-hand side of the options page. + +`URL Patterns` represent the conditions in which a `Rule Set` will be applied to +a page. To create a `URL Pattern` first make sure that you have created a `Rule +Set` with the instructions above. If not, when you click the `Add` button on +the `URL Patterns` tab, you will get an error dialog explaining that it is not +possible to create a `URL Pattern` without one or more `Rule Sets` having been +defined. + +If you have created a `Rule Set`, a new tab should appear that +contains two fields, one text box for the rule pattern and a drop-down +menu that contains all of the `Rule Sets` that have been defined thus +far. + +### Pattern Language + +The **pattern** text in a `URL Pattern` uses the glob character +`*`, to allow for a `URL Pattern` to apply to many URLs. For example, if you +would like to design a pattern that applies to all of the `http` pages under the +www.example.com domain, then you could use a pattern such as: + +``` +http://www.example.com* +``` + +Note that `URL Patterns` match the protocol, domain, port and path +portions of the url, so the pattern above will not apply to `https` +urls. The following pattern will apply to *any* site hosted at example.com: + +``` +*example.com* +``` + +# Using FiveUI + +Once some `Rule Sets` and `URL Patterns` exist in the FiveUI configuration, the +rules can be applied to a web page. Start off by navigating to a page that +satisfies one of the `URL Patterns` defined in the FiveUI options page. If that +URL is matched by one of the patterns, the FiveUI icon will change from gray to +red, and an overlay will display the number of rule violations present on the +page. + +The primary user interface is hidden by default, to avoid obscuring +the web page inadvertently. To show the list of problems, simply +click on the FiveUI icon to make the window visible. The user +interface is injected into the running page, and it should display on +top of any other user interface elements present. + +As the user navigates around sites that are matched by `URL Patterns`, +the problem list will have newly occurring problems appended to it. +All state in the dialog is maintained by the extension on a per-tab +basis, so different browser tabs can have distinct lists of problems. + +## Problems + +Problem entries will be added to the FiveUI dialog as rules report +problems on the page. Once a problem is reported, the user can click +on the arrow to the left of the message to both expand the description +of the problem, and to highlight the node of the DOM that is causing +the problem. One caveat to this is that if the node that generated +the problem exists on a page that has since been navigated away from, +the node will obviously not be highlighted. + +We illustrate this by first adding a new rule to our example Rule Set. +This rule identifies headers that start with a lower-case letter. + +```javascript +{ "name": "Header Rule Set" +, "description": "Simple rules about HTML headers." +, "rules": + [ { "name": "Disallow Empty Headers" + , "description": "Heading elements should contain text." + , "rule": function() { + fiveui.query(':header').each(function(ix, elt) { + if($(elt).text() == '') { + report('Heading does not contain text', elt); + } + }); + } + }, + { "name": "Headers should be capitalized" + , "description": "Heading elements should not start " + + "with lowercase letters." + , "rule": function() { + fiveui.query(':header').each(function(ix, elt) { + if( !fiveui.word.capitalized($(elt).text()) ) { + report('Heading is not capitalized', elt); + } + }); + } + }, + ] +} +``` + +This sample `Rule Set` demonstrates some new capabilities: + * Multiple rules in one Rule Set. + * Multi-line descriptions. + * The `fiveui.word.capitalized(...)` predicate, from the `FiveUI prelude`. +The `FiveUI Prelude` is a small collection of utilities for creating rules. + +Once adding this `Rule Set` specifying a `URL Pattern`, we can view +violations in the FiveUI Problem List. Clicking on the `expand arrow` +for a specific problem will highlight the element of the DOM that +caused the violation. + +![Expanding a Problem entry in the FiveUI Problem List highlights the element of the DOM that caused the violation.](figures/ff-heading-highlight.png) diff --git a/doc/manual_src/install.md b/doc/manual_src/install.md new file mode 100644 index 0000000..2bded6c --- /dev/null +++ b/doc/manual_src/install.md @@ -0,0 +1,85 @@ +% Install Guide + +# Installing the FiveUI Extension + +FiveUI is distributed as source code and as a browser extension for +both Google Chrome and Mozilla Firefox. This document describes the +install process for these browsers, assuming that you have the FiveUI +extension on your local computer. + +## Installing FiveUI in Firefox + +FiveUI is currently supported on Firefox 10, although it should also +work on newer versions and Firefox 3.6. Due to changes in the +long-term support and Mozilla version numbering scheme, versions 4-9 +are not supported. + +The FiveUI Firefox extension is packaged in a file called +`fiveui.xpi`. Locate this file in your distribution (or download) and +take note of the location for the following steps. We will assume +that it is located at `d:\binaries\fiveui.xpi` + + * Open Firefox, and load the `Add-ons Manager` from the main Firefox + menu. + +![Access the Firefox Add-ons Manager from the main Firefox menu](figures/ff-menu.png) + +![The Add-ons Manager Gear menu has an install from file entry.](figures/ff-add-on-installer.png) + + * Within the `Add-ons Manager`, open the Gear menu and select + `Install Add-on From File`. + + * A file dialog should open, use this to browse to the `fiveui.xpi` + file (in our case, `d:\binaries\fiveui.xpi`. + + * Click OK, and a warning dialog should appear. This dialog warns + that the FiveUI author is not verified. Because this is a + development release of FiveUI, the xpi file is not + cryptographically signed, and therefore, Firefox is unable to + verify the author identification. + + * Click on the `Install Now` button once it becomes active. + +FiveUI is now installed. The [Getting Started guide](gettingStarted) +explains how to configure and use the extension. + +## Installing FiveUI in Chrome + +All recent versions of Google Chrome should support FiveUI. + +Chrome is primarily designed to install extensions from the on-line +extension marketplace, however, local extensions can be installed by +navigating to the extension on disk. To do this, you must enter a +`file:///` url in the url bar. + +The following steps describe how to install FiveUI in Chrome, using an +extension file from the local file system. + +The FiveUI Chrome extension is packaged in a file called `fiveui.crx`. +Locate this file in your distribution (or download) and take note of +the location for the following steps. We will assume that it is +located at `d:\binaries\fiveui.crx` + + * Open Google Chrome, and enter the `file:///` url in the url bar, as + shown. In our case, the url is `file:///d:/binaries/fiveui.crx`. + +![Use a file:/// url to install local extensions in Chrome.](figures/chrome-file-url.png) + + * Chrome should open a download and install bar at the bottom of the + window and begin adding FiveUI to the browser. + +![Chrome shows an install indicator at the bottom of the window](figures/chrome-adding.png) + + * After a few minutes of processing, Chrome will open a confirmation + dialog, as shown. Confirm the installation to complete the + process. + +![Confirm the FiveUI installation to finish adding the extension.](figures/chrome-confirm-add-fiveui.png) + + * The FiveUI Button should appear in the Chrome toolbar after you + dismiss the confirmation dialog. + +![The FiveUI Button will be added to the Chrome toolbar.](figures/chrome-install-done.png) + +FiveUI is now installed. The [Getting Started guide](gettingStarted) +explains how to configure and use the extension. -- cgit v1.2.3