Mangony Handlebars Helpers

<h1 align="center">
<img width="400px" src="https://www.veams.org/downloads/logo.svg" alt="Logo Mangony" /><br>
Mangony Handlebars Helpers
</h1>

### Installation

Install `mangony-hbs-helpers` with 

``` bash
npm install mangony-hbs-helpers --save-dev
```

### Usage

Helpers are generated by passing in an instance of Handlebars.

### `lib.register(handlebars) : Object`

- `handlebars` `Handlebars` - An instance of Handlebars.

Both generates an object containing the mangony helpers and registers them with Handlebars automatically.

```js
var handlebars = require('handlebars');
var helpers = require('mangony-hbs-helpers');

helpers.register(handlebars);
```

### Helpers

#### `{{#beautifyHTML]}}`

This helper cleans up your html block by indenting and deleting spaces and line breaks.

```handlebars
{{#beautifyHTML}}
    <div class="test">
        <p>wrapper start</p>
        
        {{{yield}}}
        
        <p>wrapper end</p>
    </div>
{{/beautifyHTML}}
```

#### `{{buildPath [string] [string2] goUp=[number]}}`

- `string` `String` - First part of a path.
- `string2` `String` - Second part of a path.
- `goUp` `Number` - You can go specific folders up by defining the hash `goUp`.

This helper concatenate two strings by adding a `/`.

```handlebars
{{buildPath "src/templates" "test/file.hbs"}}
```

#### `{{concat [string] [string2]}}`

- `string` `String` - First part of a string.
- `string2` `String` - Second part of a string.

This helper concatenate two strings.

```handlebars
{{concat "src/templates/test/file" ".hbs"}}
```

#### `{{debug [context]}}`

- `context` `Object` - Log a specific context and display the value of the context.

This helper debugs a passed context.

```handlebars
{{debug this.pagename}}
```

#### `{{{embeding [path]}}}`

- `path` `String` - Path to a file.

This helper embeds the file content. 

```handlebars
{{{embeding "my/custom/file.hbs"}}}
```

#### `{{{#filter [array] by=[value] val=[val] reverse=[boolean]}}}`

- `array` `Array` - Array you want to filter.
- `by` `String` - Filter Property.
- `val` `String` - Filter value - optional.
- `reverse` `Boolean` - If you want to reverse the result set it to true.

This helper filters an array after a specific property value. 

```handlebars
{{#filter myData by="settings.hide" reverse=true}}
    {{#each this}}
        my filtered content element {{this.name}}
    {{/each}}
{{/filter}}

{{#filter myData by="settings.sitemap" val="Category Y"}}
    {{#each this}}
        my filtered content element {{this.name}} for category y.
    {{/each}}
{{/filter}}
```

#### `{{#for [from] [to] [incr]}}`

- `from` `Number` - Starting index for the loop.
- `to` `Number` - End index for the loop.
- `incr` `Number` _Optional_ - Increment number for the loop.

This helper provides a for loop which can be used to repeat content.

```handlebars
{{#for 0 2 1}}
    My Custom content 
{{/for}}
```

#### `{{#getData [from] [typeof]}}`

- `from` `String` - Id of your type.
- `typeof` `String` - Type of your data object.

This helper allows you to get the whole data object of partials, pages, data or layouts.

```handlebars
{{#getData from="my-custom-partial" typeof="partial"}}
	my data object of the partial like: {{this.filename}} | {{this.id}}
{{/getData}}
```

#### `{{getUrl [path]}}`

- `path` `String` - Absolute or relative URL path to file.

This helper prints out an URL (`http://`, `https://`, `mailto:`) or the `assets` prefix.

```handlebars
{{getUrl "my/custom/file.jpg"}} outputs "./my/custom/file.jpg" 
{{getUrl "https://google.com"}} outputs "https://google.com"
```

#### `{{#highlight [type] origin=[boolean] escapeHTML=[boolean]}}`

- `type` `String` - Language of code block.
- `origin` `Boolean` - When set to true it returns the highlighted block and the origin one
- `escapeHTML` `Boolean` - Escape HTML when set to true

This helper uses `highlight.js` to return a syntax highlighted code block.

```handlebars
{{#highlight "hbs"}}
    <div class="test">
        <p>wrapper start</p>
        {{{yield}}}
        <p>wrapper end</p>
    </div>
{{/highlight}}
```

#### `{{isFirst [idx]}}`

- `idx` `Number` - index number.

This helper returns a boolean if the element is the first one in a loop.

```handlebars
{{#each cars}}
    {{#if (isFirst idx)}}
        This is my first item.
    {{/if}}
{{/each}}
```

#### `{{#ifExists [file]}}`

- `file` `String` - Path to file.

This helper returns a boolean if the file exists under the path.

``` handlebars
{{#ifExists 'test/my-file.json'}}
    File exists!
{{else}}
    File does not exists!
{{/each}}
```

#### `{{#limit [start] [end] [data]}}`

- `start` `Number` - Starting index.
- `end` `Number` - End index.
- `data` `[Object|Array]` - Data object/array which will be iterate.

This helper returns a limited output from your data object.

```handlebars
{{#limit 0 3 data}}
    <li class="item">
        {{> item }}
    </li>
{{/limit}}
```

#### `{{{markdown [filepath] context=[data]}}}`

- `filepath` `String` - Path to your markdown file.
- `context` `Object` - Data context which you can use in your markdown file. When nothing provided it falls back to root data object.

This helper renders a markdown file into HTML by using `markdown-it`, `markdown-it-attrs` and `markdown-it-named-headers`.

It supports handlebars syntax in it and highlights code snippets by using `higlightjs`.

Next to that it provides the root context which is accessible via `rootContext`. 

```handlebars
{{{markdown "dir/file.md"}}}
```

#### `{{{mdContent [data]}}}`

- `data` `String` - Markdown content.

This helper renders a markdown content into HTML by using `markdown-it`, `markdown-it-attrs` and `markdown-it-named-headers`.

```handlebars
{{{mdContent myMarkdownContent}}}
```

#### `{{#merge [data] with=[obj|string]}}`

- `data` `Object` - Data object.
- `with` `Object|String` - JSON string or object which will be merged with `data`

This helper merges two objects into one to extend the context.

```handlebars
{{#merge this with=data}}
    <li class="item">
        {{> item }}
    </li>
{{/merge}}

{{#merge this with='{"custom": "content"}'}}
    <li class="item">
        {{> item }}
    </li>
{{/merge}}
```

#### `{{#deepMerge [data] with=[obj|string] arrayMerge=[String]}}`

- `data` `Object` - Data object.
- `with` `Object|String` - JSON string or object which will be merged with `data`.
- `arrayMerge` `String` - You can define how to merge arrays (`overwrite`, `keep`, `extend`). The default merging strategy combines the arrays by using `extend` and `overwrite` at the same time. 

This helper merges two objects into one to extend the context by using a deepmerge package.

```handlebars
{{! Default array merging strategy }}
{{#deepMerge this with=data}}
    <li class="item">
        {{> item }}
    </li>
{{/deepMerge}}

{{! Keep source array in merge process }}
{{#deepMerge this with=data arrayMerge="keep"}}
    <li class="item">
        {{> item }}
    </li>
{{/deepMerge}}

{{! Take second object in merge process }}
{{#deepMerge this with='{"custom": "content"}' arrayMerge="overwrite"}}
    <li class="item">
        {{> item }}
    </li>
{{/deepMerge}}

{{! Extend existing source array with items out of second object }}
{{#deepMerge this with='{"custom": "content"}' arrayMerge="extend"}}
    <li class="item">
        {{> item }}
    </li>
{{/deepMerge}}
```

#### `{{now [format]}}`

- `format` `String` - Date format you like to get.

This helper displays the date of now and uses [moment.js](http://momentjs.com). 

```handlebars
Current Time: {{now "Do MMMM YYYY, h:mm:ss a"}}
```

#### `{{#objToArr [object]}}`

- `object` `Object` - Object which gets flattened to an array.

This helper flattens an object to an array.

```handlebars
{{#objToArr pages}}
	{{#each this}}
	    My array element: {{this.name}}
	[{{/each}}
{{/objToArr}}
```

#### `{{#pictureData [pictures] [presets]}}`

- `pictures` `Array` - Array of all pictures.
- `presets` `Array` - Array of presets you want to display.

This helper returns an array with the images you provided as parameter. See [`image-size-export`](https://www.npmjs.com/package/image-size-export) for a simple picture module.

```handlebars
{{#pictureData pictures imagePresets}}
	<div class="doc__image-presets">
		<h2>Image Presets</h2>
		{{#each this}}
			<h3>{{uppercase presetName}}</h3>
			<table class="c-table--zebra" data-css="c-table">
				<thead class="table__head">
				<tr class="table__row is-header">
					<th class="table__headline is-th">Breakpoints</th>
					<th class="table__headline is-th">Width</th>
					<th class="table__headline is-th">Height</th>
				</tr>
				</thead>
				<tbody class="table__body">
				{{#each data}}
					<tr class="table__row">
						<td class="table__cell is-title is-td"> {{this.breakpoint}}</td>
						<td class="table__cell is-td"> {{this.width}}</td>
						<td class="table__cell is-td"> {{this.height}}</td>
					</tr>
				{{/each}}
				</tbody>
			</table>
		{{/each}}
	</div>
{{/pictureData}}
```

#### `{{random}}`

This helper returns a random number between 0 - 1000.

```handlebars
<div class="doc__image-presets" id="my-id-{{random}}">
</div>
```

#### `{{#sortArr [arr] [prop] reverse=[boolean]}}`

- `arr` `Array` - Array which you want to sort.
- `prop` `String` - String which äÄ'Ä


This helper flattens an object to an array.

```handlebars
{{#sortArr items "settings.sortOrder"}}
	{{#each this}}
	    My sorted array element: {{this.name}}
	[{{/each}}
{{/sortArr}}
```

#### `{{stringify [JSON]}}`

- `JSON` `Object` - JSON/JS object.

This helper makes a string out of JSON objects.

```handlebars
{{stringify this.jsOptions}}
```

#### `{{#times [n]}}`

- `n` `Number` - Repeating number.

This helper repeats the content n times.

```handlebars
{{#times 3}}
    My Custom content {{this}}
{{/times}}
```

### Mangony

**Mangony is yet another static site generator - fast, simple and powerful:** https://github.com/Sebastian-Fitzner/mangony

## License 

see [LICENSE.md](https://github.com/Sebastian-Fitzner/mangony-hbs-helpers/blob/master/LICENSE.md).