Sidecar API Reference 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 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

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

More attributes to be used on this element for reuse.

Properties

Name Type Argument Description

hash

Object

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 params to pass to the helper.

Properties

Name Type Argument Description

hash

Object

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

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 parameters.

Properties

Name Type Argument Description

hash

Object

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