From 2f984e3348bd9a29952892fe03f0e16538d9995c Mon Sep 17 00:00:00 2001 From: Trevor Elliott Date: Tue, 18 Jun 2013 15:46:47 -0700 Subject: Update the gettingStarted part of the manual --- doc/manual_src/gettingStarted.md | 107 +++++++++++++++++---------------------- 1 file changed, 46 insertions(+), 61 deletions(-) diff --git a/doc/manual_src/gettingStarted.md b/doc/manual_src/gettingStarted.md index bc3b463..03030cf 100644 --- a/doc/manual_src/gettingStarted.md +++ b/doc/manual_src/gettingStarted.md @@ -57,94 +57,79 @@ fields, along with an empty set of **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. +The elements of the **rules** array in the `Rule Set` are just file paths, +relative to the path of the manifest file. The contents of the file referenced +are javascript, using an exports object to expose the public parts of the rule +API. + +The required exports of a **rule** file are: + + 1. A rule name, called `name` + 2. A description, called 'description` + 3. A function that will be called as the body of the rule, named `rule` 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); - } - }); - } -} +exports.name = 'Disallow Empty Headers'; +exports.description = 'Heading elements should contain text'; +exports.rule = function(report) { + fiveui.query(':header').each(function(ix, elt) { + if($(elt).text() == '') { + report.error('Heading does not contain text', elt); + } + }); +}; ``` +Notice that the `rule` function is given a report argument that has an error +method exposed, this is how errors are reported back to the extension from the +context of a rule. + ### 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. +simple manifest that applies the empty header rule. Enter the following json +structure into a file called manifest.json: ```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" : "Header Rule Set" +, "description" : "Simple rules about HTML headers." +, "rules" : [ "emptyHeaders.js" ] } ``` -* 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. +As the above manifest references the emptyHeader.js file, we now need to +implement that rule. We'll go ahead and use the same example rule that's +defined above, placing it in the emptyHeader.js file in the same directory as +the manifest that references it. -![FiveUI uses a rich Javascript editor to highlight rule sets.](figures/ff-add-rule-set.png) + * Run `python -m SimpleHTTPServer` in the directory that contains manifest.json + and exampleHeader.js + * Next, open the options page for the FiveUI extension. + * Make sure that the `Rule Sets` tab is selected + * Click the `Add` button. + * Paste http://localhost:8000/manifest.json into the address field + * Click the save icon (a disk) -* 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. +You should now see an entry in the `Rule Sets` list that includes a `add url +pattern` button. ## 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` can be added by the use of the `add url patterns` button on a +rule set, and removed by clicking their `x` icon. `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. +Set` with the instructions above. Now you can enter a pattern in the text field +above the `add url pattern` button, using the pattern language defined below. ### 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 +*, 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: -- cgit v1.2.3