Module: View/HbsHelpers

Handlebars helpers.

These functions are to be used in Handlebars templates.

Example:

// to register all the helpers at once
Handlebars.registerHelper(require('view/hbs-helpers'));

// to register a single helper
const HbsHelpers = require('view/hbs-helpers');
Handlebars.registerHelper('fieldOfType', HbsHelpers.fieldOfType);

Methods


<static> arrayJoin(array, glue)

Joins all the elements of an array by a glue string.

Parameters:
Name Type Description
array Array.<string>

Array of strings to join.

glue string

The string to join them with.

Returns:

All of the strings joined with the given glue.

Type
string

<static> buildRoute(options)

Builds a route based on hashes sent on Handlebars helper.

Example:

{{buildRoute context=this.context}}
{{buildRoute model=myModel action="create"}}
{{buildRoute module="Employees" action="edit"}}

If both module and model are sent, module will take precedence over model.module. Similarly, id will take precedence over model.id.

Parameters:
Name Type Description
options Object

Handlebars options hash.

Properties
Name Type Description
hash Object

More parameters to be used by this helper. It needs at least one of options.hash.module, options.hash.model or options.hash.context.

Properties
Name Type Argument Default Description
module string <optional>
options.hash.model.module

The name of the module.

model Data/Bean <optional>
options.hash.context.get('model')

The model to extract the module and/or id.

context Core/Context <optional>

A context to extract the module from.

id string <optional>
options.hash.model.id

The id of the bean record.

action string <optional>

The action name.

Returns:

The built route.

Type
string

<static> component(layout, name)

Creates a layout or a view in a given layout.

Parameters:
Name Type Description
layout View/Layout

Layout that the new layout should be created in.

name string

Name of the component to be created.

Returns:

The placeholder text for the component.

Type
Handlebars.SafeString

<static> eachOptions(key, hbsOptions)

Iterates through options specified by a key.

The options collection is retrieved from the language helper.

Parameters:
Name Type Description
key string

Options key.

hbsOptions function

HBS options.

Returns:

HTML string.

Type
string

<static> eq(val1, val2, options)

Executes a given block if given values are equal.

Parameters:
Name Type Description
val1 string

First value to compare.

val2 string

Second value to compare.

options Object

Additional options.

Properties
Name Type Description
fn function

The block to execute if the given values are equal.

inverse function

The block to execute if the given values are not equal.

Returns:

Result of the block execution if the given values are equal or the result of the inverse block.

Type
string

<static> field(view [, options])

Creates a field widget.

Example:

{{field view model=mymodel template=edit parent=fieldset}}
Parameters:
Name Type Argument Description
view View/View

Parent view

options Object <optional>

Optional params to pass to the field.

Properties
Name Type Argument Description
model Backbone.Model <optional>

The model associated with the field.

template string <optional>

The name of the template to be used.

parent Field <optional>

The parent field of this field.

Returns:

HTML placeholder for the widget.

Type
Handlebars.SafeString

<static> fieldOfType(type, label)

Creates a field widget.

This helper is used for fields that don't have a view definition.

Parameters:
Name Type Description
type string

Field type.

label string

Label key.

Returns:

HTML placeholder for the widget.

Type
Handlebars.SafeString

<static> fieldValue(bean, field [, options])

Extracts the value of the given field from the given bean.

Parameters:
Name Type Argument Description
bean Data/Bean

Bean instance.

field string

Field name.

options Object <optional>

Additional options.

Properties
Name Type Argument Default Description
hash.defaultValue string <optional>
''

Default value to return if field is not set on the bean.

Returns:

Field value of the given bean. If field is not set the default value or empty string.

Type
string

<static> firstChars(text, n)

Formats a given string by returning the first n characters.

Parameters:
Name Type Description
text string

The text to trim.

n number

The number of characters to return.

Returns:

The first n characters of text.

Type
string

<static> formatCurrency(number, currencyId)

Formats a given currency amount according to user preferences.

Parameters:
Name Type Description
number number

The number to format.

currencyId string | Object

The currency identifier.

Returns:

The formatted number.

Type
string

<static> formatDate(date [, options])

Formats a given date according to user preferences.

Parameters:
Name Type Argument Description
date Date | string

The date to format.

options Object <optional>

More attributes to be used on this element for reuse.

Properties
Name Type Argument Description
hash Object <optional>

More parameters to be used by this helper.

Properties
Name Type Argument Description
dateOnly boolean <optional>

Flag to determine whether to return just date current user date/time preference format.

Returns:

The formatted date.

Type
string

<static> getModuleName(module [, options])

Gets the translated module name (plural or singular).

For instance, to get the singular version of the module name (make sure LBL_MODULE_NAME_SINGULAR is defined in the module language strings of your module):

{{getModuleName 'Accounts'}}

To get the plural version, set plural to true and make sure LBL_MODULE_NAME is defined in the module language strings of your module:

{{getModuleName 'Accounts' plural=true}}

You can pass a default value that will be returned in case the module language string of your module is not found. The following example will return 'Module' (since LBL_MODULE is defined in the module strings or the app strings):

{{getModuleName 'undefinedModule' defaultValue='LBL_MODULE'}}

In the worst case scenario (the module language string is not found and no default value is specified), the module key name is returned. The following example will return 'undefinedModule':

{{getModuleName 'undefinedModule'}}
Parameters:
Name Type Argument Description
module string

The module defined in the language strings.

options Object <optional>

Optional params to pass to the helper.

Properties
Name Type Argument Description
hash Object <optional>

More parameters to be used by this helper.

Properties
Name Type Argument Description
plural boolean <optional>

Returns the plural form if true, singular otherwise.

defaultValue string <optional>

Value to be returned if the module language string is not found.

Returns:

The module name.

Type
string

<static> has(val, array, options)

Executes a given block if a given array has a value.

Parameters:
Name Type Description
val string | Object

Value to look for.

array Object | Array

Array or hash object to check.

options Object

Additional options.

Properties
Name Type Description
fn function

The block to execute if val is found.

inverse function

The block to execute if val is not found.

Returns:

Result of the block execution if array contains val or the result of the inverse block.

Type
string

<static> isSortable(module, fieldViewdef, options)

We require sortable to be the default if not defined in either field viewdefs or vardefs. Otherwise, we use whatever is provided in either field vardefs or fields viewdefs where the viewdef has more specificity.

Parameters:
Name Type Description
module string

Module name.

fieldViewdef Object

The field view definition (e.g. looping through meta.panels.field it will be 'this').

options Object

Additional options.

Properties
Name Type Description
fn function

The block to execute if sortable.

Returns:

Result of the block execution if sortable, otherwise empty string.

Type
string

<static> log(value)

Logs a value.

Parameters:
Name Type Description
value *

The value to log.


<static> match(val1, val2, options)

Same as the eq helper, but the second value is a (string) regex expression. This works around Handlebars' lack of support for regex literals.

Note that modifiers are not supported.

Parameters:
Name Type Description
val1 string

The string to test.

val2 string

The expression to match against. It will be passed directly to the RegExp constructor.

options Object

Additional options.

Properties
Name Type Description
fn function

The block to execute if val1 matches val2.

inverse function

The block to execute if val1 does not match val2.

Returns:

Result of the block execution if val1 matches val2 or the result of the inverse block.

Type
string

<static> nl2br(s)

Converts \r\n, \n\r, \r, and \n to <br>.

Parameters:
Name Type Description
s string

The raw string to filter.

Returns:

The given s with all newline characters converted to <br> tags.

Type
Handlebars.SafeString

<static> notEq(val1, val2, options)

Opposite of eq helper.

Parameters:
Name Type Description
val1 string

first value to compare

val2 string

second value to compare.

options Object

Additional options.

Properties
Name Type Description
fn function

The block to execute if the given values are not equal.

inverse function

The block to execute if the given values are equal.

Returns:

Result of the block execution if the given values are not equal or the result of the inverse block.

Type
string

<static> notHas(val, array, options)

Executes a given block if a given array doesn't have a value.

Parameters:
Name Type Description
val string | Object

Value to look for.

array Object | Array

Array or hash object to check.

options Object

Additional options.

Properties
Name Type Description
fn function

The block to execute if val is not found.

inverse function

The block to execute if val is found.

Returns:

Result of the block execution if the array doesn't contain val or the result of the inverse block.

Type
string

<static> notMatch(val1, val2, options)

Same as the notEq helper but second value is a (string) regex expression. This works around Handlebars' lack of support for regex literals.

Note that modifiers are not supported.

Parameters:
Name Type Description
val1 string

The string to test.

val2 string

The expression to match against. It will be passed directly to the RegExp constructor.

options Object

Additional options.

Properties
Name Type Description
fn function

The block to execute if val1 does not match val2.

inverse function

The block to execute if val matches val2.

Returns:

Result of the block execution if the given values are not equal or the result of the inverse block.

Type
string

<static> partial(name, component [, properties] [, options])

Helper for rendering a partial template. This helper can load a partial from the templateOptions or from the same relative location as the current template.

{{partial 'partial-name' componentFrom defaultProperties dynamicProperty=value}}

The data supplied to the partial with be an object with the list of dynamicPropertys merged into defaultProperties object (defaults to empty object if not explicitly passed).

For fields:

{{partial 'edit' this properties fallbackTemplate='detail'}}

For layouts:

{{partial 'ActivityStream' this properties}}

For views:

{{partial 'record' this properties}}
Parameters:
Name Type Argument Description
name string

Name of the partial.

component View/Component

The view component.

properties Object <optional>

Data supplied to the partial. options.hash is merged into this before it is used for the template. This allows the partial to provide dynamic parameters on top of the default properties. The original component is kept as templateComponent in these properties.

options Object <optional>

Optional parameters.

Properties
Name Type Argument Description
hash Object <optional>

The hash of the optional params.

Properties
Name Type Argument Default Description
module Object <optional>
component.module

Module to use.

fallbackTemplate Object <optional>

Fallback template for field partials.

Returns:

The HTML of the partial template.

Type
Handlebars.SafeString

<static> relativeTime(iso8601, options)

Creates a relative time element to display the human readable related time.

To provide an automatic update of this relative time, use a plugin like sugar.liverelativetime.js.

Parameters:
Name Type Description
iso8601 string

The ISO-8601 date string to be used for a new date.

options Object

Handlebars options hash.

Properties
Name Type Description
hash Object

More parameters to be used by this helper.

Properties
Name Type Argument Description
title string <optional>

The title attribute. Defaults to current user date/time preference format.

dateOnly boolean <optional>

Setting this to true will format the title attribute with the user-formatted date only.

Returns:

The relative time like 10 minutes ago.

Type
string

<static> str(key [, module] [, content])

Retrieves an i18n-ed string by key.

Parameters:
Name Type Argument Description
key string

Key of the label.

module string <optional>

Module name.

content string <optional>

Template content.

Returns:

The string for the given label key.

Type
string