|
| 1 | +# Check Message Template |
| 2 | + |
| 3 | +Axe-core uses a custom template to handle dynamic check messages (messages that use the `data` property to output values or to determine which message to display). The structure for the messages is as follows: |
| 4 | + |
| 5 | +## Simple Message |
| 6 | + |
| 7 | +A simple message is just a string that doesn't use the `data` property. Most checks uses this format. |
| 8 | + |
| 9 | +```json |
| 10 | +{ |
| 11 | + "messages": { |
| 12 | + "pass": "Simple message for a passing check" |
| 13 | + } |
| 14 | +} |
| 15 | +``` |
| 16 | + |
| 17 | +## Message with Data |
| 18 | + |
| 19 | +A message can also use the `data` property to output information from the check. If `data` is a String, Boolean, or Number, you can use the syntax `${data}` to have the message output the value of the `data` property. |
| 20 | + |
| 21 | +```js |
| 22 | +// check.js |
| 23 | +this.data(10); |
| 24 | + |
| 25 | +// check.json |
| 26 | +{ |
| 27 | + "messages": { |
| 28 | + "pass": "Passed with a value of ${data}" |
| 29 | + // => "Passed with a value of 10" |
| 30 | + } |
| 31 | +} |
| 32 | +``` |
| 33 | + |
| 34 | +If `data` is an object, you can access properties of the object using the syntax `${data.propName}`. |
| 35 | + |
| 36 | +```js |
| 37 | +// check.js |
| 38 | +this.data({ |
| 39 | + contrast: '3:1', |
| 40 | + fontSize: '12px' |
| 41 | +}); |
| 42 | + |
| 43 | +// check.json |
| 44 | +{ |
| 45 | + "messages": { |
| 46 | + "fail": "Color-contrast failed with a contrast of ${data.contrast} and font size of ${data.fontSize}" |
| 47 | + // => "Color-contrast failed with a contrast of 3:1 and font size of 12px" |
| 48 | + } |
| 49 | +} |
| 50 | +``` |
| 51 | + |
| 52 | +## Singular and Plural Messages |
| 53 | + |
| 54 | +If the message needs to to know how many items are in the `data` property to determine the type of language to use (singular or plural), you can structure the message to use `singular` and `plural` properties. Use the syntax `${data.values}` to have the message output a comma-separated list of the items (`data.values` is provided by the template code for you). |
| 55 | + |
| 56 | +```js |
| 57 | +// check.js |
| 58 | +this.data(['item1', 'item2']); |
| 59 | + |
| 60 | +// check.json |
| 61 | +{ |
| 62 | + "messages": { |
| 63 | + "fail": { |
| 64 | + "singular": "Attribute ${data.values} is not allowed", |
| 65 | + "plural": "Attributes: ${data.values} are not allowed" |
| 66 | + } |
| 67 | + // => Attributes: item1, item2 are not allowed |
| 68 | + } |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +## Message Determined by Data |
| 73 | + |
| 74 | +Lastly, a message can use the `data` property to determine which message to display. Structure the message to use properties whose keys are the possible values of `data.messageKey`. You should also provide a `default` message that will be displayed if `messageKey` is not set. |
| 75 | + |
| 76 | +```js |
| 77 | +// check.js |
| 78 | +this.data({ |
| 79 | + messageKey: 'imgNode' |
| 80 | +}); |
| 81 | + |
| 82 | +// check.json |
| 83 | +{ |
| 84 | + "messages": { |
| 85 | + "incomplete": { |
| 86 | + "default": "Color-contrast could not be determined" |
| 87 | + "bgImage": "Element's background color could not be determined due to a background image", |
| 88 | + "imgNode": "Element's background color could not be determined because element contains an image node" |
| 89 | + } |
| 90 | + // => Element's background color could not be determined because element contains an image node |
| 91 | + } |
| 92 | +} |
| 93 | +``` |
| 94 | + |
| 95 | +The messages can still use the syntax `${data.propName}` to access other properties on the `data` property. |
| 96 | + |
| 97 | +## Migrating From doT.js Template in Translations |
| 98 | + |
| 99 | +Axe-core use to use doT.js for it's temple library. To migrate from doT.js in a translation file, do the following: |
| 100 | + |
| 101 | +- If the message used `{{=it.data}}` or `{{=it.data.propName}}`, change the message to use the syntax `${data}` or `${data.propName}`. |
| 102 | + |
| 103 | +```diff |
| 104 | +{ |
| 105 | + "messages": { |
| 106 | +- "incomplete": "Check that the <label> does not need be part of the ARIA {{=it.data}} field's name" |
| 107 | ++ "incomplete": "Check that the <label> does not need be part of the ARIA ${data} field's name" |
| 108 | + } |
| 109 | +} |
| 110 | +``` |
| 111 | + |
| 112 | +- If the message used `{{=it.data && it.data.length` to determine using singular or plural language, change the message structure of the message to instead use the `singular` and `plural` properties. Replace `{{=it.data.join(', ')}}` with `${data.values}`. |
| 113 | + |
| 114 | +```diff |
| 115 | +{ |
| 116 | + "messages": { |
| 117 | +- "fail": "Attribute{{=it.data && it.data.length > 1 ? 's' : ''}} {{=it.data.join(', ')}} {{=it.data && it.data.length > 1 ? 'are' : ' is'}} not allowed |
| 118 | ++ "fail": { |
| 119 | ++ "singular": "Attribute ${data.values} is not allowed", |
| 120 | ++ "plural": "Attributes: ${data.values} are not allowed" |
| 121 | ++ } |
| 122 | + } |
| 123 | +} |
| 124 | +``` |
0 commit comments