1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
# The FiveUI Prelude
The FiveUI Prelude provides a basic set of utilities to assist with
writing rules and rule sets for the FiveUI browser extension.
The following format is used to describe Rules and RuleSets for the
FiveUI tool.
FiveUI uses a JSON-like representation for RuleSets and Rules, as follows:
## Rule Set Syntax
Rule Sets take the form of:
```javascript
{
/**
* A short descriptive name for the Rule Set.
*
* @type {!string}
*/
'name': 'Short Rule Set Name',
/**
* A detailed description of the Rule Set, potentially
* including links back to the original source.
*
* @type {!string}
*/
'description': 'Rule Set description '
+ 'Multiple lines can be used to describe the Rule Set',
/**
* A free-form string field for licensing information.
*/
'license': 'Apache 2.0',
/**
* A list of dependencies, resolved relative to the rule set json file.
*/
'dependencies': []'
/**
* A list of rules to load and evaluate on pages
* that are matched to this RuleSet.
*
* @type Array.<Rule>
*/
'rules': []
};
```
## Rule Manifest Syntax
Individual Rules are specified with the following manifest:
```javascript
{
/**
* A short descriptive name for the Rule.
*
* @type {!string}
*/
'name': 'Short Rule name',
/**
* A detailed description of the RuleSet, potentially
* including links back to the original source.
*
* @type {!string}
*/
'description': 'Description of the underlying guideline that '
+ 'this rule enforces.',
/**
* A Javascript function that represents a guideline.
*
* The rule function should invoke `report(descr, node)` when the
* guideline is violated.
*
* The rule function has access to the FiveUI prelude and jQuery.
*/
'rule': []
};
```
## Rule Syntax
Rules are encoded as javascript files that specify an unbound exports
object. This object is expected to have three fields:
name: A short, unique, but readable name for the rule.
description: A textual description.
rule: a function that takes one object as a parameter.
In the context of the function provided as the **rule** field, the
**this** object will point to an anonymous object that contains the
other fields of the rule, **name** and **description**. In addition
to the fields of the rule, there is a field named **ruleSet**, which
is a reference to the enclosing `Rule Set`.
The function parameter is an object with one method: 'error' which
takes an error message and a DOM element as its two parameters. The
DOM element is used by FiveUI to describe the location of the error,
so it should be chosen to best represent the location on the page
where the error occurred. If the DOM element is unspecified, the rule
will run, but less debugging information will be provided to the user.
```javascript
exports.name = "imagesAltText";
exports.description = "Each image should have alt text.";
exports.rule = function(report) {
fiveui.query('img')
.filter(function (i) {
var altAttr = $(this).attr('alt');
return altAttr == undefined || altAttr == '';
})
.each(function (i, e) {
report.error('Image has no alt text', e);
});
};
```
Find more examples in the [GitHub repository](https://github.com/GaloisInc/FiveUI/tree/master/exampleData).
|
