npm package: @journeyapps-solutions/cc-pdf-handlebars
Description: Journey Apps Handlebars Util Module
Author: Anton Van Zyl
Latest version: 1.1.0

# cc-util-handlebar

[![CircleCI](https://circleci.com/gh/journeyapps-solutions/cc-pdf-handlebars/tree/master.svg?style=svg&circle-token=946e6173af8a0c53630b3be5879eec91d882d4f0)](https://circleci.com/gh/journeyapps-solutions/cc-pdf-handlebars/tree/master)

This is a implementation of unique reusable functions for Journey Apps.
This module is considered compatible with sharedJS and CloudCode.

Any function that is deemed reusable and not available in lodash should/can be added here.

Familiarize yourself with the functions of Lodash https://lodash.com/

## Usage

To use, add the following at the top of your Cloud Code or sharedJS

```js
const ccPDFHandlebars = require('@journeyapps-solutions/cc-pdf-handlebars');
ccPDFHandlebars.init(handlebars); //Will add all the handlebars to the runtime

```

### Modules


### Format
Format is helpful to get the data to display correctly. 
[Code Here](src/main/util/filter.js)

```
// All examples use the data below:
let _data = {
    example_date : new Date(1988,9,20),
    example_number: 100
} 
```

#### Format Dates
Format the date to default or custom format. The dates are formatted using node `moment` module.
```
{{format_date example_date}} //Output : 1988/10/20
{{format_date example_date "DD/MM/YYYY"}} //Output : 10/20/1988

//These are quick references to common formats
{{format_date_toEuropean example_date}} //Output : 20/10/1988
{{format_date_toAmerican example_date}} //Output : 20/10/1988
{{format_date_toSouthAfrican example_date}} //Output : 1988/10/20
{{format_date_toInternational example_date}} //Output : 1988/10/20

//You can also format time HH:mm
{{format_time example_date}} //Output : 00:00
```

#### Format Numbers
Formatting of numbers to limit the decimals
```
{{format_number_toFixed example_number 2}} //Output : 100.00
```

### Operators
Operators will most likely be your most used helpers, They are extreamly valuable to add logic to your handlebars template. 
[Code Here](src/main/util/operator.js)

*Note: All Examples below are written to show the `<h1>Display Me</h1>` tag.*

#### Default Known Operators

Available Operators:
* eq (equal)
* ne (Not Equal)
* lt (Less Than)
* gt (Greater Than)
* lte (Less or Equal Than)
* gte (Greater or Equal Than)
* and (And)
* or (Or)

```
//Quick Example
{{#if (eq "one" "one")}} <h1>Display Me</h1>{{/if}}
{{#if (ne "one" "two")}} <h1>Display Me</h1>{{/if}}
{{#if (lt 1 2)}} <h1>Display Me</h1>{{/if}}
{{#if (gt 2 1)}} <h1>Display Me</h1>{{/if}}
{{#if (lte 2 2)}} <h1>Display Me</h1>{{/if}}
{{#if (gte 2 2)}} <h1>Display Me</h1>{{/if}}
{{#if (and (eq "one" "one") (eq "two" "two"))}} <h1>Display Me</h1>{{/if}}
{{#if (or (eq "one" "one") (eq "one" "two"))}} <h1>Display Me</h1>{{/if}}

//Chaining Example
{{#if (and (gt 2 1) (or (eq "one" "one") (ne "one" "two")))}} <h1>Display Me</h1>{{/if}}

// As you can see you can chain all the operators using `and` or `or` 
```
#### Custom Operators

```
{{#if (isBlank "")}} <h1>Display Me</h1>{{/if}} //Checks if value is blank
{{#if (exists "")}} <h1>Display Me</h1>{{/if}} //Checks if value exists, opposite of isBlank
```
```
let example_data = [{id: 123, name: "James", state:"complete"},{id: 321, name: "Damian", state:"pending"},{id: 2133, name: "roger", state:"pending"}];

//Checks if the id is contained in the object array 
{{#if (includes_id example_data 123)}} <h1>Display Me</h1>{{/if}} 
```
```
let example_data = ["James", "Roger", "Mark","Polo"];

//Check if the object is contained in the array
{{#if (includes_item example_data "Roger")}} <h1>Display Me</h1>{{/if}}
```
```
let _multiChoice = [{key: "completed", display: "Completed"},{key: "pending", display: "Pending"},{key: "failed", display: "Failed"}]

//Check if the key is in the array, usefull for multiple selects
{{#if (includes_key _multiChoice "completed")}} <h1>Display Me</h1>{{/if}}

```

#### Filter

You want to filter something, we have got you covered. 
[Code Here](src/main/util/filter.js)

You can filter by a specific field
```
let example_data = [{name:"James"},{name:"Justin"},{name:"Tammy"},];

<table>
    {{#each (filter_by_field example_data "name" "James" )}}
        <tr>
            <td>{{name}}</td>
        </tr>
    {{/each}}
</table>
```

You can filter by a specific field that uses key (Example: Singe Choice, Multi Choice)
```
let example_data = [{"state": {key: "completed", display: "Completed"}},{"state": {key: "pending", display: "Pending"}},{"state": {key: "failed", display: "Failed"}},];

<table>
    {{#each (filter_by_key example_data "state" "completed" )}}
        <tr>
            <td>{{state.display}}</td>
        </tr>
    {{/each}}
</table>
```

You can break down the array into groups for better display. Example, having only 2 photos per row. This is usefull in splitting up things that wont fit.
```
let example_data = ["Photo 1", "Photo 2", "Photo 3", "Photo 4"];

<table>
    {{#grouped_each example_data 2}}
    <tr>
        {{#each this}}
            <td>{{this}}</td>
        {{/each}}
        </tr>
    {{/grouped_each}}
</table>

```

### PDF Sass
These are custom helpers to use with Rocket PDF. 
[Code Here](src/main/handlebars-helper.js)

Display a signature with a line below it safely
```
{{printSignature example_signature}} //Prints out the signature
```

When using checkbox ([Docs Here](https://journeyapps-solutions.github.io/cc-pdf-sass/#!/checkbox)) you can use the below helper to indicate a check. 

```
let example_data = { sex: {
    key: "male",
    display: "Male"
}};

<div class="row-13">
    <label class="column-2 form-label">Male</label>
    <div class="column-10">
        <div class="checkbox {{isChecked sex.key "male"}} flush-left"></div>
    </div>
</div>
<div class="row-13">
    <label class="column-2 form-label">Female</label>
    <div class="column-10">
        <div class="checkbox {{isChecked sex.key "female"}} flush-left"></div>
    </div>
</div>
```

#### Documentation
All code is clearly documented, please see code for more details.

## Installation

#### Per machine

```
yarn add @journeyapps-solutions/cc-pdf-handlebars --save
```

#### Per CloudCode task

```
yarn add @journeyapps-solutions/cc-pdf-handlebars
```

## Deploying

```
yarn version
```

## Development
This lib is meant to work for both CloudCode and SharedJs. What this means is that we need to ensure we only create functions that will work in both environments.

Every function must have a corresponding Unit Test.

## Testing

We use tape and yarn to test the functions.

```js
yarn test
```