zup-dustjs-helpers

This project contains some extra helpers of Dust.js.

Install

npm install zup-dustjs-helpers

Use

const Dust = require('dustjs-linkedin')
require('zup-dustjs-helpers')

const template = '{@truncate key=number/}'
const context = { number: 1.234567 }

Dust.renderSource(template, context, function(err, out) {
  console.log(out)
})

Test

Run npm test.

Extra Helpers

ifArray

Verify if some object is a array. It render the body content if the elemet of the given key is a array.

key - the key of the object to be checked - Mandatory parameter

Examples

Given this context:

{
  someArray: [1, 2, 3, 4, 5, 6]
}

this template:

{#someArray}{.}{@ifArray key=someArray}{@sep},{/sep}{/ifArray}{/someArray}

renders to:

1,2,3,4,5,6

Timestamp

Get the current date in a given format using a utc offset.

The supported date formats can be found here: http://momentjs.com/docs/#/displaying/format/

format {String} - The date format to render
utfOffset {String} - The UTC offset, the default is based on GMT timezone

Examples

This template:

{ "date": "{@timestamp format="MM-DD-YYYY" /}" }

renders to:

{ "date": "08-12-2016" }

Truncate

Truncate a number in a given decimal places. The default is 2.

key - the key of the object - Mandatory parameter
places {Int} - the number of places to truncate

Examples

Given this context:

{
  number: 1.23456
}

this template:

{ "someNumber": "{@truncate key=number places=3 /}" }

renders to:

{ "someNumber": "1.234" }

findAndReplace

Replace characters based on a given regex.

key - the key of the object that you want search - Mandatory parameter
regex {String} - the pattern you want to find - Mandatory parameter
replaceBy {String} - if some pattern match, replace by it. If empty string is given
the helper simply removes the pattern found from original object

Examples

Given this context:

{
 phone: '[phone]'
}

this template:

{ "somePhone": "{@findAndReplace key=phone regex="[+-\s\(\)]" replaceBy="" /}" }

renders to:

{ "somePhone": "553412345678" }

dateTransform

Transform a date in a given format to other format.

The supported date formats can be found here: http://momentjs.com/docs/#/displaying/format/

key - the key of the object - Mandatory parameter
fromFormat {String} - the current date format
toFormat {String} - the target date format

Examples

Given this context:

{
 date: '2016-08-12T20:30:00-03:00'
}

this template:

{@dateTransform key=date fromFormat="YYYY-MM-DDTHH:mm:ssZ" toFormat="YYYY-MM-DD HH:mm:ss"

renders to:

2016-08-12 20:30:00

Contains

Checks whether in a given array keys and values exist. It was inspired by this helper: dustjs-helpers-extra, and modified to have an 'else' block. If condition is satisfied the helper will render the block, otherwise it will render the 'else' block.

Search behavior

• Only key is given: the helper will look for the existence of the key in an array of Objects (e.g. [{a: 1},{b: 2}]).
• Only value is given: the helper will look for the existence of some value in an array of values (e.g. [1,2,3] or ['a','b','c']) - Not Objects.
• Both are given: the helper will look for the existence of some/every object that has the given key and value.

{@contains arr=myObj key="myKey" value="myValue" scope="once/all"}block{:else}ElseBlock{/contains}

arr - the array containing the objects to be iterated - Mandatory parameter

key - the key in the object
value - the value to be checked.
If the value is a boolean it should be passed as string (e.g. 'true' or 'false').

scope - 'once' or 'all'. The default is 'once'.
  'once' checks whether there is at least one element in the array has the given key and value.
  'all' checks whether all elements in the array have the given key and value.

Examples

Given this context:

{
  users: [
    { 'user': 'Fulano', 'age': 19, 'active': true, 'admin': false},
    { 'user': 'Beltrano', 'age': 19, 'active': true, 'admin': true}
  ]
}

this template:

{@contains arr=users key="active" value="true" scope="all"}
block
{/contains}

renders to:

block

and this template:

{@contains arr=users key="phone"}
block
{:else}
other block
{/contains}

renders to:

other block

Now suppose this context:

{
  letters: [ 'a', 'b', 'c', 'd', 'e' ]
}

this template:

{@contains arr=letters value="c"}
block
{/contains}

renders to:

block

max

Computes the maximum value of array.

key - the key of the array - Mandatory parameter

If the array is empty `null` is returned, rendering an empty string.

Examples

Given this context:

{
  intArray: [1, 7, 3, 9, -2, 6],
  charArray: ['a', 'c', 'b', 'd'],
  stringArray: ['a', 'aaa', 'aa', ''],
  otherArray: ['1', '15', '3', '120'],
  emptyArray: []
}

these template:

{
  "maxInt": "{@max key=intArray /}",
  "maxChar": "{@max key=charArray /}",
  "greatestString": "{@max key=stringArray /}",
  "maxNum": "{@max key=otherArray content="number" /}",
  "maxLexicalOrder": "{@max key=otherArray /}",
  "withoutMax": "{@max key=emptyArray /}",
  "notNumber": "{@max key=charArray /}"
}

renders respectively to:

{
  "maxInt": "9",
  "maxChar": "d",
  "greatestString": "aaa",
  "maxNum": "120",
  "maxLexicalOrder": "3",
  "withoutMax": "",
  "notNumber": ""
}

substr

Extracts parts of a string.

Parameters

key - the key of the string to be extracted - Mandatory parameter

begin {Integer} - the position where to start the extraction - Optional parameter

length {Integer} - the number of characters to extract - Optional parameter

end {Integer} - the position (up to, but not including) where to end the extraction. If end and length is informed, length will take priority - Optional parameter

Examples

Given this context:

{aString: 'testsubstring'}

this template:

{@substr key=aString, begin="0" length="4" /}

renders to:

test

pad

Pads string/number on the left and/or right sides if it's shorter than length.

Parameters

key - the key of the object (String or Number) to padding - Mandatory parameter

length {Integer} - The padding length - Optional parameter

with {String} - The character used to fill the gap - Optional parameter

direction {String} - The padding direction - Optional parameter
Should be one of below:
  'left' - pads string on the left side.
  'right' - pads string on the right side.
If the direction is not informed the helper will pad in 'both' directions.

Examples

Given this context:

{
  aString: 'test',
  aNumber: 12.3
}

this template:

{@pad key=aNumber length=6 direction='right' with='0' /}
{@pad key=aNumber length=6 with='0' /}
{@pad key=aString length=6 with=' ' direction='left' /}
{@pad key=aString length=6 with='-' /}
{@pad key=aNumber length=2 /}

renders to:

12.300
0012.3
  test
-test-
12.3

Extra Filters

toUpper

Convert the string as a whole to uppercase.

Examples

Given this context:

{aString: 'testUpperCase'}

this template:

{aString|toUpper}

renders to:

TESTUPPERCASE

toLower

Convert the string as a whole to lowercase.

Examples

Given this context:

{aString: 'TESTlowerCASE'}

this template:

{aString|toLower}

renders to:

testlowercase

Extra Filters

trim

Removes leading and trailing whitespace.

Examples

Given this context:

{
  first: '  this is a test  ',
  second: ' \t All is <Fair> in Love & War \t '
  third: '\n\ttest\t\n   ',
}

this template:

{first|trim}
{second|trim|s}
{@pad key="{third|trim}" length=6 with="-" /}

renders to:

this is a test
All is <Fair> in Love & War
-test-