Add documentation about template helper functions (#703)

1 files changed, 577 insertions, 0 deletions

diff --git a/docs/templates.md b/docs/templates.md
new file mode 100644
index 00000000..1c9081d2
--- /dev/null
+++ b/docs/templates.md
@@ -0,0 +1,577 @@
+# Templates
+
+## Helpers
+
+Yomichan supports several custom Handlebars helpers for rendering templates.
+The source code for these templates can be found [here](../ext/bg/js/template-renderer.js).
+
+
+### `dumpObject`
+
+Converts an object to a pretty-printed JSON string.
+This function can be helpful for debugging values when creating templates.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#dumpObject}}<i>&lt;object&gt;</i>{{/dumpObject}}</code>
+
+  * _`object`_ <br>
+    The object to convert.
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  <pre>{{#dumpObject}}{{.}}{{/dumpObject}}</pre>
+  ```
+
+  Output:
+  ```html
+  <pre>{
+      "key": "value"
+  }</pre>
+  ```
+
+  Preview:
+  ```html
+  {
+      "key": "value"
+  }
+  ```
+</details>
+
+
+### `furigana`
+
+Converts a definition to its furigana representation.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#furigana}}<i>&lt;definition&gt;</i>{{/furigana}}</code>
+
+  * _`definition`_ <br>
+    The definition to convert.
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{#furigana}}{{.}}{{/furigana}}
+  ```
+
+  Output:
+  ```html
+  <ruby>読<rt>よ</rt></ruby>む
+  ```
+
+  Preview
+  <pre><ruby>読<rt>よ</rt></ruby>む</pre>
+</details>
+
+
+### `furiganaPlain`
+
+Converts a definition to its simplified furigana representation.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#furiganaPlain}}<i>&lt;definition&gt;</i>{{/furigana}}</code>
+
+  * _`definition`_ <br>
+    The definition to convert.
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{~#furiganaPlain~}}{{.}}{{~/furiganaPlain~}}
+  ```
+
+  Output:
+  ```html
+  読[よ]む
+  ```
+</details>
+
+
+### `multiLine`
+
+Replaces newline characters with a forced HTML line break `<br>`.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#multiLine}}<i>text with multiple lines</i>{{/multiLine}}</code>
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{#kanjiLinks~}}
+  some
+  multiline
+  text
+  {{~/kanjiLinks}}
+  ```
+
+  Output:
+  ```html
+  some<br>multiline<br>text
+  ```
+
+  Preview:
+  <pre>some<br>multiline<br>text</pre>
+</details>
+
+
+### `regexReplace`
+
+Uses a [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) to replace a pattern with the specified text.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#regexReplace <i>regex</i> <i>replacement</i> <i>[flags]</i>}}<i>text-to-modify</i>{{/regexReplace}}</code>
+
+  * _`regex`_ <br>
+    The raw string used to create the regular expression. This value is passed to the [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) constructor.
+  * _`replacement`_ <br>
+    The text used to replace pattern matches. This supports the standard [special capture group replacements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Specifying_a_string_as_a_parameter) as supported by the web browser.
+  * _`flags`_ _(optional)_ <br>
+    Optional flags to pass to the [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) constructor.
+  * _`text-to-modify`_ <br>
+    The text that the regular expression is applied to.
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{#regexReplace "\(([^)]*)\)" "$1" "g"~}}Here is (some) (text) (in) (parentheses){{~/regexReplace}}
+  ```
+
+  Output:
+  ```html
+  Here is some text in parentheses
+  ```
+</details>
+
+
+### `regexMatch`
+
+Uses a [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) to return only the content that matches the pattern.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#regexMatch <i>regex</i> <i>[flags]</i>}}<i>text-to-modify</i>{{/regexMatch}}</code>
+
+  * _`regex`_ <br>
+    The raw string used to create the regular expression. This value is passed to the [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) constructor.
+  * _`flags`_ _(optional)_ <br>
+    Optional flags to pass to the [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) constructor.
+  * _`text-to-modify`_ <br>
+    The text that the regular expression is applied to.
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{#regexMatch "\(([^)]*)\)" "g"~}}Here is (some) (text) (in) (parentheses){{~/regexMatch}}
+  ```
+
+  Output:
+  ```html
+  (some)(text)(in)(parentheses)
+  ```
+</details>
+
+
+### `mergeTags`
+
+Creates a set of all unique tags for the definition and returns a text representation of the tags separated by commas.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#mergeTags <i>definition</i> <i>isGroupMode</i> <i>isMergeMode</i>}}{{/mergeTags}}</code>
+
+  * _`definition`_ <br>
+    The root definition object.
+  * _`isGroupMode`_ _(optional)_ <br>
+    Whether or not the display mode is the 'group' mode.
+  * _`isMergeMode`_ <br>
+    Whether or not the display mode is the 'merge' mode.
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{~#mergeTags definition group merge}}{{/mergeTags~}}
+  ```
+
+  Output:
+  ```html
+  v5m, vt, JMdict (English)
+  ```
+</details>
+
+
+### `eachUpTo`
+
+Similar to the built-in `each` function, but iterates up to a maximum count.
+If the iterable is falsy or empty, the `else` condition will be used.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#eachUpTo <i>iterable</i> <i>maxCount</i>}}<i>(modification)</i>{{else}}<i>(else-modification)</i>{{/eachUpTo}}</code>
+
+  * _`iterable`_ <br>
+    The object that should be looped over. A JavaScript [`for...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of) loop is used, so the object only needs to be iterable.
+  * _`maxCount`_ _(optional)_ <br>
+    The maximum number of entries to loop over.
+  * _`modification`_ <br>
+    The template used to modify the value. The context is changed to the current item of iteration.
+  * _`else-modification`_ <br>
+    The template used in case the iterable is falsy or empty. The context is unchanged.
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{~#eachUpTo someArray 5}}{{{.}}}<br>{{else}}Empty{{/mergeTags~}}
+  ```
+
+  Output:
+  ```html
+  someArray[0]<br>someArray[1]<br>someArray[2]<br>someArray[3]<br>someArray[4]<br>
+  ```
+
+  Preview:
+  <pre>someArray[0]<br>someArray[1]<br>someArray[2]<br>someArray[3]<br>someArray[4]<br></pre>
+</details>
+
+
+### `spread`
+
+Uses the JavaScript [spread](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) operator to convert one or more iterables into a single array.
+This allows it to be used similar to an [`Array.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat) operation.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#spread <i>iterable1</i> <i>iterable2</i> <i>...</i> <i>iterableN</i>}}{{/spread}}</code>
+
+  * _`iterableN`_ <br>
+    A variable amount of iterable objects to combine into a single array.
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{#each (spread array1 array2)}}{{{.}}}<br>{{/each}}
+  ```
+
+  Output:
+  ```html
+  array1[0]<br>array1[1]<br>array2[0]<br>array2[1]<br>
+  ```
+
+  Preview:
+  <pre>array1[0]<br>array1[1]<br>array2[0]<br>array2[1]<br></pre>
+</details>
+
+
+### `op`
+
+Performs a simple operation on one, two, or three arguments. The operations available are:
+
+* Unary operators: `+`, `-`, `~`, `!`
+* Binary operators: `+`, `-`, `/`, `*`, `%`, `**`, `==`, `!=`, `===`, `!==`, `<`, `<=`, `>`, `>=`, `<<`, `>>`, `>>>`, `&`, `|`, `^`, `&&`, `||`
+* Ternary operators: `?:`
+
+If an unknown operator is specified, the `undefined` value is returned.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#op <i>operator</i> <i>operand1</i> <i>[operand2]</i> <i>[operand3]</i>}}{{/op}}</code>
+
+  * _`operator`_ <br>
+    One of the unary, binary, or ternary operators.
+  * _`operand1`_ <br>
+    The first operand of the operation.
+  * _`operand2`_ _(Optional)_<br>
+    The second operand of the operation.
+  * _`operand3`_ _(Optional)_<br>
+    The third operand of the operation.
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{#if (op "===" value1 value2)}}Values are equal{{/op~}}<br>
+  {{~#op "-" value1}}{{/op~}}<br>
+  {{~#op "?:" value1 "a" "b"}}{{/op}}
+  ```
+
+  Output:
+  ```html
+  Values are equal<br>-32<br>a
+  ```
+
+  Preview:
+  <pre>Values are equal<br>-32<br>a</pre>
+</details>
+
+
+### `get`
+
+Gets a value from the custom state stack.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#get <i>name</i>}}{{/get}}</code>
+
+  * _`name`_ <br>
+    The name of the variable to get.
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{#get "some-text"}}{{/get}}
+  ```
+
+  Output:
+  ```html
+  This is the value of some-text!
+  ```
+</details>
+
+
+### `set`
+
+Assigns a value to the custom state stack.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#set <i>name</i>}}<i>value</i>{{/get}}</code><br>
+  <code>{{#set <i>name</i> <i>value</i>}}{{/get}}</code><br>
+
+  * _`name`_ <br>
+    The name of the variable to assign.
+  * _`value`_ <br>
+    The value of the variable.
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{#set "some-text"}}This is the value of some-text!{{/set~}}
+  {{~#set "some-number" 32}}{{/set}}
+  ```
+
+  Output:
+  ```html
+  ```
+</details>
+
+
+### `scope`
+
+Pushes a new variable scope to the custom state stack.
+Variable assignments are applied to the most recent scope,
+and variable lookups will start from the most recent scope and work backwards until a value is found.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#scope}}<i>content</i>{{/scope}}</code>
+
+  * _`name`_ <br>
+    The name of the variable to assign.
+  * _`value`_ <br>
+    The value of the variable.
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{~#set "key" 32}}{{/set~}}
+  {{~#get "key"}}{{/get~}},
+  {{~#scope~}}
+    {{~#get "key"}}{{/get~}},
+    {{~#set "key" 64}}{{/set~}}
+    {{~#get "key"}}{{/get~}},
+  {{~/scope~}}
+  {{~#get "key"}}{{/get~}}
+  ```
+
+  Output:
+  ```html
+  32,32,64,32
+  ```
+</details>
+
+
+### `property`
+
+Repeatedly gets a property of an object.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#property <i>object</i> <i>property1</i> <i>property2</i> <i>...</i> <i>propertyN</i>}}{{/property}}</code>
+
+  * _`object`_ <br>
+    The initial object to use.
+  * _`propertyN`_ <br>
+    A chain of property names to get on the object.
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{property someObject "field" 0 "toString"}}
+  ```
+
+  Output:
+  ```html
+  function toString() { [native code] }
+  ```
+</details>
+
+
+### `noop`
+
+No-op. Returns the inner contents of the template.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#noop}}<i>content</i>{{/noop}}</code>
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{noop}}Unchanged content{{/noop}}
+  ```
+
+  Output:
+  ```html
+  Unchanged content
+  ```
+</details>
+
+
+### `isMoraPitchHigh`
+
+Returns whether or not a mora will have a high pitch, given the index of the mora and the position of the downstep.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#isMoraPitchHigh <i>index</i> <i>position</i>}}{{/isMoraPitchHigh}}</code>
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{#if (isMoraPitchHigh 1 2)}}High pitch{{else}}Low pitch{{/if}}
+  ```
+
+  Output:
+  ```html
+  High pitch
+  ```
+</details>
+
+
+### `getKanaMorae`
+
+Returns an array of the mora for a kana string.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#getKanaMorae <i>kana-string</i>}}{{/getKanaMorae}}</code>
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{#each (getKanaMorae "よみちゃん")}}{{{.}}}<br>{{/each}}
+  ```
+
+  Output:
+  ```html
+  よ<br>み<br>ちゃ<br>ん<br>
+  ```
+
+  Preview:
+  <pre>よ<br>み<br>ちゃ<br>ん<br></pre>
+</details>
+
+
+## Legacy Helpers
+
+Yomichan has historically used Handlebars templates to generate the HTML used on the search page and results popup.
+To simplify the and improve Yomichan's capabilities, the HTML elements are now generated directly using a different process.
+
+As such, there are several leftover Handlebars helpers that do not have much utility for Anki templates, but are kept for compatibility purposes.
+
+
+### `kanjiLinks`
+
+Replaces kanji characters in the text with linkified versions.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#kanjiLinks}}<i>text</i>{{/kanjiLinks}}</code>
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{#kanjiLinks}}読む{{/kanjiLinks}}
+  ```
+
+  Output:
+  ```html
+  <a href="#" class="kanji-link">読</a>む
+  ```
+
+  Preview:
+  <pre><a href="#" class="kanji-link">読</a>む</pre>
+</details>
+
+
+### `sanitizeCssClass`
+
+Sanitizes text so it can be used as a CSS class name.
+
+<details>
+  <summary>Syntax:</summary>
+
+  <code>{{#sanitizeCssClass}}<i>text</i>{{/sanitizeCssClass}}</code>
+</details>
+<details>
+  <summary>Example:</summary>
+
+  ```handlebars
+  {{#sanitizeCssClass}}some text with many types of characters !@#$%^ 読む{{/sanitizeCssClass}}
+  ```
+
+  Output:
+  ```html
+  some_text_with_many_types_of_characters________読む
+  ```
+</details>