HandlebarsHelpers - Foundry Virtual Tabletop Developer API

HandlebarsHelpers

A collection of Handlebars template helpers which can be used within HTML templates.

Constructor

new HandlebarsHelpers()

Methods

(static) checked() → {string}

For checkboxes, if the value of the checkbox is true, add the "checked" property, otherwise add nothing.

Returns:

Type: string

(static) colorPicker(options) → {Handlebars.SafeString}

Render a pair of inputs for selecting a color.

Parameters:

Name Type Description

options

object

Helper options

Properties

Name	Type	Attributes	Description
`name`	string	<optional>	The name of the field to create
`value`	string	<optional>	The current color value
`default`	string	<optional>	A default color string if a value is not provided

Returns:

Type: Handlebars.SafeString

(static) concat(…values) → {Handlebars.SafeString}

Concatenate a number of string terms into a single string. This is useful for passing arguments with variable names.

Example

Concatenate several string parts to create a dynamic variable

{{filePicker target=(concat "faces." i ".img") type="image"}}

Parameters:

Name	Type	Attributes	Description
`values`	Array.<string>	<repeatable>	The values to concatenate

Returns:

Type: Handlebars.SafeString

(static) disabled() → {string}

For use in form inputs. If the supplied value is truthy, add the "disabled" property, otherwise add nothing.

Returns:

Type: string

(static) editor(options) → {Handlebars.SafeString}

Construct an editor element for rich text editing with TinyMCE

Parameters:

Name Type Description

options

object

Helper options

Properties

Name	Type	Attributes	Default	Description
`target`	string	<optional>		The named target data element
`owner`	boolean	<optional>		Is the current user an owner of the data?
`button`	boolean	<optional>		Include a button used to activate the editor later?
`editable`	boolean	<optional>		Is the text editor area currently editable?
`documents`	boolean	<optional>	`true`	Replace dynamic document links?
`rollData`	Object \| function	<optional>		The data object providing context for inline rolls
`content`	string	<optional>	`""`	The original HTML content as a string

Returns:

Type: Handlebars.SafeString

(static) filePicker(options) → {Handlebars.SafeString|string}

Render a file-picker button linked to an field

Parameters:

Name Type Description

options

object

Helper options

Properties

Name	Type	Attributes	Description
`type`	string	<optional>	The type of FilePicker instance to display
`target`	string	<optional>	The field name in the target data

Returns:

Type: Handlebars.SafeString | string

(static) localize() → {string}

Translate a provided string key by using the loaded dictionary of localization strings.

Example

Translate a provided localization string, optionally including formatting parameters

<label>{{localize "ACTOR.Create"}}</label> <!-- "Create Actor" -->
<label>{{localize "CHAT.InvalidCommand" command=foo}}</label> <!-- "foo is not a valid chat message command." -->

Returns:

Type: string

(static) numberFormat(value, options) → {Handlebars.SafeString}

A string formatting helper to display a number with a certain fixed number of decimals and an explicit sign.

Parameters:

Name Type Description

value

number

A numeric value to format

options

object

Additional options which customize the resulting format

Properties

Name	Type	Attributes	Default	Description
`decimals`	number	<optional>	`0`	The number of decimal places to include in the resulting string
`sign`	boolean	<optional>	`false`	Whether to include an explicit "+" sign for positive numbers *

Returns:

The formatted string to be included in a template

Type: Handlebars.SafeString

(static) numberInput() → {Handlebars.SafeString}

Render a form input field of type number with value appropriately rounded to step size.

Returns:

Type: Handlebars.SafeString

(static) radioBoxes(name, choices, options) → {Handlebars.SafeString}

A helper to create a set of radio checkbox input elements in a named set. The provided keys are the possible radio values while the provided values are human readable labels.

Examples

The provided input data

let groupName = "importantChoice";
let choices = {a: "Choice A", b: "Choice B"};
let chosen = "a";

The template HTML structure

<div class="form-group">
  <label>Radio Group Label</label>
  <div class="form-fields">
    {{radioBoxes groupName choices checked=chosen localize=true}}
  </div>
</div>

Parameters:

Name Type Description

name

string

The radio checkbox field name

choices

object

A mapping of radio checkbox values to human readable labels

options

object

Options which customize the radio boxes creation

Properties

Name	Type	Description
`checked`	string	Which key is currently checked?
`localize`	boolean	Pass each label through string localization?

Returns:

Type: Handlebars.SafeString

(static) rangePicker(options) → {Handlebars.SafeString}

Render a pair of inputs for selecting a value in a range.

Parameters:

Name Type Description

options

object

Helper options

Properties

Name	Type	Attributes	Description
`name`	string	<optional>	The name of the field to create
`value`	number	<optional>	The current range value
`min`	number	<optional>	The minimum allowed value
`max`	number	<optional>	The maximum allowed value
`step`	number	<optional>	The allowed step size

Returns:

Type: Handlebars.SafeString

(static) select() → {Handlebars.SafeString}

A helper to assign an <option> within a <select> block as selected based on its value Escape the string as handlebars would, then escape any regexp characters in it

Returns:

Type: Handlebars.SafeString

(static) selectOptions(choices, options) → {Handlebars.SafeString}

A helper to create a set of <option> elements in a <select> block based on a provided dictionary. The provided keys are the option values while the provided values are human readable labels. This helper supports both single-select as well as multi-select input fields.

Examples

The provided input data

let choices = {a: "Choice A", b: "Choice B"};
let value = "a";

The template HTML structure

<select name="importantChoice">
  {{selectOptions choices selected=value localize=true}}
</select>

The resulting HTML

<select name="importantChoice">
  <option value="a" selected>Choice A</option>
  <option value="b">Choice B</option>
</select>

Using inverted

let choices = {"Choice A": "a", "Choice B": "b"};
let value = "a";

The template HTML structure

<select name="importantChoice">
  {{selectOptions choices selected=value inverted=true}}
</select>

Using nameAttr and labelAttr with objects

let choices = {foo: {key: "a", label: "Choice A"}, bar: {key: "b", label: "Choice B"}};
let value = "b";

The template HTML structure

<select name="importantChoice">
  {{selectOptions choices selected=value nameAttr="key" labelAttr="label"}}
</select>

Using nameAttr and labelAttr with arrays

let choices = [{key: "a", label: "Choice A"}, {key: "b", label: "Choice B"}];
let value = "b";

The template HTML structure

<select name="importantChoice">
  {{selectOptions choices selected=value nameAttr="key" labelAttr="label"}}
</select>

Parameters:

Name Type Description

choices

object

A mapping of radio checkbox values to human readable labels

options

object

Helper options

Properties

Name	Type	Attributes	Default	Description
`selected`	string \| Array.<string>	<optional>		Which key or array of keys that are currently selected?
`localize`	boolean	<optional>	`false`	Pass each label through string localization?
`blank`	string	<optional>		Add a blank option as the first option with this label
`nameAttr`	string	<optional>		Look up a property in the choice object values to use as the option value
`labelAttr`	string	<optional>		Look up a property in the choice object values to use as the option label
`inverted`	boolean	<optional>	`false`	Use the choice object value as the option value, and the key as the label instead of vice-versa

Returns:

Type: Handlebars.SafeString