HTML Document Handlebars/JavaScript Helper Functions


Overview


Handlebars is a templating language that can be used to reference answers from a form submission. These references can be embedded within HTML to define how a document should be structured.


Handlebars/JavaScript document helper functions are used in conjunction with document tags to expand on their functionality. These functions are applied to the information returned from an invoked document tag. As a rule, when sending values to a function if the value is not a document tag it is best practice to surrounded it in either single or double quotation marks.


Function Details Information

Function Name: Name used to call function.

Input: Tags/information that the function will accept.

Brief: Description of function.

Code example: Example of code utilizing function in document.

Output: Result of executed function.

*: Additional note on function


DocketManager Custom Functions

Function NameInputBriefCode Example
each
an array
each function will iterate through an entire array from front to back.

<!-- {{#each OrderItems}} --> 

{{Number}}<br/>

<!-- {{/each}} --> 




withSort
an array, attribute to sort by in array, optional second function to determine the order in which array is sorted/displayed
withSort function will iterate through an array by the attribute chosen to sort by specified by the second argument passed to the function.

{{#withSort Orders “OrderNumber”}}

{{OrderNumber}}<br/>

{{/with}}




sortBy


sort direction specifier
sortBy function can be used in conjunction with withSort function to determine whether or not the array being used will be sorted in ascending or descending order (0 - 10 or 10 - 0).

{{#withSort Orders "Number" sortBy="asc"}}

{{#withSort Orders "Number" sortBy="desc"}}


dateFormat


date tag, format specifier
dateFormat function allows you to specify the desired format for dates on your documents. Formatting the date is done by specifying the M, D and Y. If you wanted your date to appear as feb 21, 2018 you would put “MMM DD, YYYY”.

{{dateFormat OrderDate}} - Output: Feb 07 2018


{{dateFormat OrderDate format=”MMMM YYYY”}} - Output: February 2018


{{dateFormat OrderDate format=”MMMM DD, YYYY”}} - Output: February 07, 2018

if



value looking to see if exists
if function will take a tag and if it is not null, actually has a value, it will run the code surrounded by the opening and closing if tags.

<!-- {{#if UnpaidAmount}} --> 

<p>true</p>

<!-- {{/if}} -->


is
initial value, test value
is function allows you to compare two values and if both are equal run the code surrounded by the is tags. Below example is comparing two tags, the same tag, which results in true and thus will run the code surrounded by the opening and closing is tags.

<!-- {{#is UnpaidAmount UnpaidAmount}} --> 

<p>true</p>

<!-- {{/is}} --> 





currency
amount, optional specifiers for thousandsSeperator, currency and decimal
currency function will take a numeric value and format it to its currency equivalent.

{{currency UnpaidAmount}} - Output: $12.35

{{currency FinalInvoiceTotal thousandsSeparator="S"}} Output: $1L000.00


{{currency FinalInvoiceTotal currency="C"}} Output: C1,000.00


{{currency FinalInvoiceTotal decimal="D"}} Output: $1,000D00


*All options, thousandsSeperator, currency and decimal can be used simultaneously i.e.

{{currency FinalInvoiceTotal thousandsSeparator="S" currency="C" decimal="D"}} Output: C1S00D00

leftPad
initial value, padding length, character to pad initial value with
leftPad function will add characters to the left of the initial value and the number of characters added will be indicated by the second argument (padding length).

{{leftPad OrderNumber 15}} - Output: 000000000051037

{{leftPad OrderNumber 15 character="L"}} - Output: LLLLLLLLLL51037


rightPad
initial value, padding length, character to pad initial value with
rightPad function will add characters to the right of the initial value and the number of characters added will be indicated by the second argument (padding length).

{{rightPad OrderNumber 15}} - Output: 510370000000000

{{rightPad OrderNumber 15 character="R"}} - Output: 51037RRRRRRRRRR


lengthEqual
an array
lengthEqual function will take an array and a possible length and if the length passed is the same length as the array then the function will run the code surrounded by the opening and closing lengthEqual tags.

<!-- {{#lengthEqual OrderItems 3}} -->

<p>true</p>

<!-- {{/lengthEqual}} --> 



*If there were 3 order items on the order the test would pass and the output would be: true

inArray
an array, value to check for in array, the attribute of the array that you are looking to search for the specified value in

inArray function will look through an array for a specified attribute and if the value found is then the function will run the code surrounded by the opening and closing inArray tags.




<!-- {{#inArray OrderItems 510375 property="Number"}} --> 

<p>true</p>

<!-- {{/inArray}} --> 




ifCond
first value, operator, second value

ifCond function will take two values and compare them with a specified operator. If the operation evaluates to true then the function will run the code surrounded by the opening and closing ifCond tags.




<!-- {{#ifCond OrderNumber "==" 51037}} --> 

<p>true</p>

<!-- {{/ifCond}} -->



*Operators available:



== - equals

=== - equals

< - less than

<= - less than or equal

> - greater than

>= - greater than or equal

&& - and

|| - or


*Operator has to be surrounded in quotation marks but first and second value do not. 

withFirst
an array, index position in the array to stop before
withFirst function will iterate through an array and stop right before it gets to the value passed as the second argument to this function. Arrays use zero based indexing so if you wanted to get the first two order items on an order you would pass 2 as the index position. This works because 0 is the position of the first element in the array and 1 is the second and because it is stopping before the number passed as an argument it will pass back the first two elements 0  and 1.

<!-- {{#withFirst OrderItems 2}} --> 

{{Number}}<br/>

<!-- {{/withFirst}} --> 




withAfter
an array, index position in the array to start from

withAfter function will iterate through an array starting from the value passed as the second argument to this function. Arrays use zero based indexing so if you wanted to get the all of the values starting from the second element you would pass 1 as the index position. This works because 0 is the position of the first element in the array and 1 is the second and because it is starting from the number passed as an argument it will pass back all values starting from the second element onwards.

<!-- {{#withAfter OrderItems 1}} --> 

{{Number}}<br/>

<!-- {{/withAfter}} --> 


timeFormat
time tag
timeFormat function allows you to format times returned to documents.

<!-- {{#each OrderItems}} --> 

{{timeFormat EstimatedGraphicTime}}<br/>

<!-- {{/each}} --> 


Assemble IO Functions

Function NameInputBriefCode Example
toFixed
number to format and specified precision after the decimal
toFixed function takes a value and a number then returns a value with the specified number of decimal places.

{{toFixed FinalPretaxTotal 2}} - Output: 834.84


ceil
a numeric value
the ceil function returns the smallest integer greater than or equal to a given number.

{ceil Number}} - Output: 34


*Number tag’s value before ceil was applied 33.23423



Making Sense of the Assemble IO Handlebars-Helpers Library


https://github.com/helpers/handlebars-helpers - link to the GitHub repository where you will find the assemble io handlebars-helpers library


The lib folder is where you will find the actual library of code that holds and describes the functions that the assemble io library gives us access too. Here you will find javascript files separated by category. These categories group together functions that provide similar operations. i.e. the math.js file holds functions that perform mathematical operations and the string.js file holds functions that perform string parsing and manipulation.


https://github.com/helpers/handlebars-helpers/blob/master/lib/math.js - links to the math.js file in the GitHub repository


Once inside one of the javascript files you will find documented code that shows the use, purpose and logic behind all of the functions we have available to us.


Take the add function located on lines 22 - 39 of the math.js file.

/**

* test comment, everything in between /** and */ is a comment about the function

*/


These characters represent a comment, code that is not compiled or used when the function is called, comments throughout the javascript files will explain the purpose of the function as well as the parameters the function accepts and the return value type. In this case the function describes returning the sum of ‘a’ plus ‘b’, it accepts two parameters, a number and another number and it also returns a number. On to the function declaration, helpers.add describes the name of the function. The string immediately after ‘helpers.’ will be the name used when invoking the method on our documents. I.e. helpers.add - {{add Number Number}}. Then the ‘function(a, b)’ section of the method declaration describes the parameters/way in which the function accepts parameters. In this case the function is accepting two numeric values. I.e. {{add Number Number}}. Although the function shows a comma in between a and b, that has no bearing on our documents. It is a requirement of the javascript language when providing parameters for functions. When we invoke a function, our reference to function names and parameters will only be separated by a single whitespace. I.e. {{add Number Number}}. Below is the math.js add function taken from https://github.com/helpers/handlebars-helpers/blob/master/lib/math.js


/**

 * Return the sum of `a` plus `b`.

 *

 * @param {Number} `a`

 * @param {Number} `b`

 * @return {Number}

 * @api public

 */


helpers.add = function(a, b) {

  if (isNumber(a) && isNumber(b)) {

    return Number(a) + Number(b);

  }

  if (typeof a === 'string' && typeof b === 'string') {

    return a + b;

  }

  return '';

};