Helper functions
In order to facilitate the writing and use of converters, a number of handlebars helper functions are available in the context of TEv2, that extend the built-in helper functions of Handlebars.
Helper functions would typically use variables as specified in the converter profile for the TEv2 tool that they are used in.
Helper functions can be used within handlebars expressions. Their input is the evaluated value of the expression that follows the call, possibly with extra options.
{{<helperfunction> <element> <argument>="<value>"}}
{{capFirst entry.term}}
{{noRefs entry.glossaryText type="markdown"}}
List of built-in helpers
Here is a summary of the handlebar helpers that can always be used; you can click on the helper to navigate to a more detailed description of how they work (with examples):
Helper | Functional summary |
---|---|
#if | conditionally render a text block. |
#unless | this is the inverse of #if . |
#each | Iterates over a list of elements. Inside the block, you can use this to reference the element being iterated over. |
#with | Enables you to change the evaluation context of template-parts. |
lookup | Allows for dynamic parameter resolution using Handlebars variables. |
capFirst
The function of the helper capFirst
is to capitalize every first character from every word in a string.
{{capFirst entry.glossaryTerm}} // e.g. "converter profile" becomes "Converter Profile"
{{capFirst entry.glossaryText}} // e.g. "This is a description; for SOME TERM" becomes "This Is A Description; For SOME TERM"
The helper capFirst
replaces the first character of every word of its argument with the capitalized equivalent.
Words are obtained by splitting the input on space characters.
It takes a string as input, splits the string at spaces, capitalizes the first character of every split item,
reconstructs the input string fomr the split items, and returns the result.
log
The function of the helper log
is to output a text string to the log of a tool that uses a converter from which it is called. This allows users to enhance debugging output.
This helper extends the [functionality of the log
helper that is built into [Handlebars itself]https://handlebarsjs.com/guide/builtin-helpers.html#log). The helper is based on tslog, which has lots of other features.
Particular to our log
helper is the feature that allows users to suppress log messages. This is useful, for example, when using a converter in the HRGT that determines whether or not to allow an MRG entry to appear in the HRG that is being created. In such cases, the log would be littered with log messages that no output is being generated, which can now be suppressed.
This feature is implemented through the log level silent
. Other log level values are provided by tslog. When a log level isn't specified, it defaults to warn
.
// The following logs a warning of the form '<path>/<file>@<line>:pos', which specifies where an error occurred.
{{log '<errmsg>:' err.dir '/' err.file '@' err.line ':' err.pos level='warn'}}"
// The following logs the text 'This is an informational message'
{{log level='info' 'This is an informational message'}}
// Examples below will prevent errors caused by the conversion call from being logged
{{log level='silent' 'This message will not be logged'}}
{{regularize entry.term}}{{log level='silent'}}
noRefs
The function of the helper noRefs
is to replace all TermRefs from a string, with its (capitalized) showtext
. Capitalization is done by the helper capFirst
.
The usefulness of the noRefs
helper has its limits.
For example, in a context that allows two or more (customized) syntaxes for TermRefs, the noRefs
helper can miss one or more of these (custom) syntaxes, producing a result that will not be rendered as expected by the static site generator.
One way to deal with such situations is to identify where it may occur, and try to provide input to the noRefs
helper that does not contain (such) TermRefs.
In the concrete situation of popups, for which typically glossaryText
fields are used that might produce such erroneous renderings, a workaround would be to add a popupText
field (or so) whose value is manually constructed from the glossaryText
, and is void of (such) TermRefs.
The following tabs show how this helper works on the following input:
[Markdown](link), <a href="link">HTML</a>, `[showtext](someterm@somescope)`
- (No type specified)
- type="markdown"
- type="markdown, html, interpreter"
- type="/[(?<showtext>[^]]+)]((?:[^)]+))/, html"
Calling {{noRefs entry.glossaryText}}
results in:
[Markdown](link), <a href="link">HTML</a>, Showtext
Calling {{noRefs entry.glossaryText type="markdown"}}
results in:
Markdown, <a href="link">HTML</a>, Showtext
Calling {{noRefs entry.glossaryText type="markdown, html, interpreter"}}
results in:
Markdown, HTML, Showtext
Note that the TermRef is also seen as a markdown link, and hence remo
Calling {{noRefs entry.glossaryText type="/\[(?<showtext>[^\]]+)\]\((?:[^)]+)\)/, html"}}
results in:
Markdown, HTML, Showtext
The helper noRefs
uses the configured type
to convert all references to the showtext
property of the interpreted reference.
It also capitalizes the showtext
replacement using the capFirst
helper.
It takes the input, finds matches using the configured syntax-type
, and uses the capitalized interpreted showtext
property as a replacement, after which the output is returned.
Three standard values are available to be used as the value for the type
option. Multiple values may be provided, in which case the values are interpreted in order from left to right. If no value is provided, 'interpreter
' is used as the default type
. If a type
is provided that does not match any of the standard type
values, the value is assumed to be a custom regex.
Available type
values:
type | Description |
---|---|
interpreter | Uses the regex of the configured interpreter to find matches. |
html | Uses the regex <a\b[^>]*?>(?<showtext>.*?)<\/a> to find HTML <a> tags and uses the value in between the opening and closing tag as showtext . |
markdown | Uses the regex \[(?<showtext>[^\]]+)\]\((?:[^)]+)\) to find Markdown hyperlinks and uses the link text as showtext . |
custom | A value for type that does not match any of the standard type values is assumed to be a custom regex. |
regularize
The function of the helper regularize
is convert human readable text into a regularized text, which is a common text format within TEv2 (particularly in MRG entries) for automated processing.
// Input (entry.term): "EX(ample)"
{{regularize entry.term}}
// Output: "ex-ample"
The helper regularize
converts the input string into a regularized text, according to the regularization process.
localize
The function of the helper localize
is to convert an absolute URL to a relative path within a particular website context, enhancing internal navigation efficiency and consistency.
The website context is specified by the website
value of the MRG in the converter profile.
- `website` = `https://github.com/tno-terminology-design/tev2-specifications/tree/master`
- `website` is something else
// Input (entry.navurl): "https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs/specs/syntax/handlebars-helper-functions"
{{regularize entry.navurl}}
// Output: "/docs/specs/syntax/handlebars-helper-functions"
// Input (entry.navurl): "https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs/specs/syntax/handlebars-helper-functions"
{{regularize entry.navurl}}
// Output: "https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs/specs/syntax/handlebars-helper-functions"
The helper localize
parses the value it was given as a URL and compares it to the website
value of the MRG in the converter profile. If both the host
values (e.g., tno-terminology-design.github.io) match, the pathname
of the URL is returned. If the given value cannot be interpreted as a URL, or the host
values do not match, the input value is returned. This can be useful in situations where external links (URL's pointing to a website other than the current host
) are handled differently from internal links.
ifValue
The ifValue
helper allows you to conditionally display text based on various comparisons. This can be useful for showing or hiding content depending on specific values, statuses, or other conditions.
- equals
- notEqual
- greaterThan
- greaterThanOrEqual
- lessThan
- lessThanOrEqual
- isNull
- isTruthy
- isFalsy
equals
The equals
option checks if a value is strictly equal to a specified value. This is useful when you want to display content only if a field matches exactly with the expected value.
Example: Display a Warning for Deprecated Terms
If the status of a term is "deprecated," show a warning message.
{{#ifValue entry.status equals="deprecated"}}
**Warning**: this term is deprecated!
{{/ifValue}}
- What This Does: If
entry.status
is "deprecated", the warning text is displayed.
notEqual
The notEqual
option checks if a value is not equal to the specified value. This is useful for excluding content based on certain conditions.
Example: Exclude Active Terms
If a term's status is not "active," display a note.
{{#ifValue entry.status notEqual="active"}}
Note: This term is not currently active.
{{/ifValue}}
- What This Does: If
entry.status
is anything other than "active", the note is displayed.
greaterThan
The greaterThan
option checks if a numeric value is greater than a specified number. This is useful for comparisons like age, quantity, etc.
Example: Age Check for Adults
Show a message if the age is greater than 18.
{{#ifValue entry.age greaterThan=18}}
You are an adult.
{{/ifValue}}
- What This Does: If
entry.age
is greater than 18, the message "You are an adult." is displayed.
greaterThanOrEqual
The greaterThanOrEqual
option checks if a numeric value is greater than or equal to a specified number.
Example: Age Check for Voting Eligibility
Show a message if the age is 18 or older.
{{#ifValue entry.age greaterThanOrEqual=18}}
You are eligible to vote.
{{/ifValue}}
- What This Does: If
entry.age
is 18 or more, the message "You are eligible to vote." is displayed.
lessThan
The lessThan
option checks if a numeric value is less than a specified number.
Example: Age Check for Minors
Show a message if the age is less than 18.
{{#ifValue entry.age lessThan=18}}
You are a minor.
{{/ifValue}}
- What This Does: If
entry.age
is less than 18, the message "You are a minor." is displayed.
lessThanOrEqual
The lessThanOrEqual
option checks if a numeric value is less than or equal to a specified number.
Example: Age Check for Underage
Show a message if the age is 18 or less.
{{#ifValue entry.age lessThanOrEqual=18}}
You are underage.
{{/ifValue}}
- What This Does: If
entry.age
is 18 or less, the message "You are underage." is displayed.
isNull
The isNull
option checks if a value is null
or undefined
.
Example: Check if a Value is Null
Show a message if a term's description is missing.
{{#ifValue entry.description isNull=true}}
No description available.
{{/ifValue}}
- What This Does: If
entry.description
isnull
orundefined
, the message "No description available." is displayed.
isTruthy
The isTruthy
option checks if a value is "truthy" (non-zero, non-null, non-empty string, etc.).
Example: Check if a Feature is Enabled
Show a message if a feature is enabled.
{{#ifValue entry.isEnabled isTruthy=true}}
The feature is enabled.
{{/ifValue}}
- What This Does: If
entry.isEnabled
is "truthy", the message "The feature is enabled." is displayed.
isFalsy
The isFalsy
option checks if a value is "falsy" (0
, null
, undefined
, ""
, false
, etc.).
Example: Check if a Feature is Disabled
Show a message if a feature is disabled.
{{#ifValue entry.isEnabled isFalsy=true}}
The feature is disabled.
{{/ifValue}}
- What This Does: If
entry.isEnabled
is "falsy", the message "The feature is disabled." is displayed.