[//]: # ( ns__file unit: standard, comp: README.md )

[//]: # ( ns__custom_start beginning )

[//]: # ( ns__custom_end beginning )

[//]: # ( ns__start_section intro )

[//]: # ( ns__custom_start description )


simple file management for handlebars, including helpers, partials and template files

[//]: # ( ns__custom_end description )

[//]: # ( ns__custom_start afterDescription )

[//]: # ( ns__custom_end afterDescription )

[//]: # ( ns__custom_start badges )

[//]: # ( ns__start_section usageSection )


[//]: # ( ns__custom_end badges )

[//]: # ( ns__end_section intro )

[//]: # ( ns__start_section api )

[//]: # ( ns__custom_start APIIntro )

* :clipboard: Why
* :white_check_mark: What
* :wrench: Basic Usage
* :paperclip: Built In Handlers
* :thumbsup: Adding Helpers
* :computer: Adding Partials
* :ledger: API

:clipboard: Why

Handlebars is super simple, but there's a learning curve to getting it set up with template files, helpers and partials.

:white_check_mark: What

A tool that provides:
1. the popular libraries of helpers out of the box
2. automatic registration of custom helpers and partials
3. a tool for loading a template from a file.

:wrench: Basic Usage

Include the package:
``
npm i barbells
`

Then:
1. create a handlebars instance with all the handlebars helpers and partials for the project;
2. use it by loading a template from a file.
`
const {prepareHandlebars} = require('barbells')
const {loadFileTemplate} = require('barbells')
const projectDir = "path/to/parentDir" // where parentDir has optional partials and helpers directories

const Handlebars = await prepareHandlebars(projectDir)

const myContext = {foo: "bar"} // an object with whatever you want...
cond pathString = "~/templates/myTemplate.hbs"

const fileTemplate = await loadFileTemplate(pathString, null, Handlebars)

const fileText = await fileTemplate(context)

`


:paperclip: Built In Handlers

1. You have full use of two packages of helpers:
* handlebars-helpers
* just-handlebars-helpers

For instance, {{capitalizeFirst 'super cat'}} produces Super cat and {{and value1 value2}} will result in the value1 && value2.

2. There are a few added helpers, really just for legacy usage:
* {{safe text}} shows text without escape characters. That is helpful if you are getting unwanted escapes of certain special characters such as quote marks.
* {{openCurly}} produces a left curly brace {, {{closeCurly}} returns }.

And if you want to use this with a geenee template you can add the geenee abbreviations as well.



:thumbsup: Adding Helpers


3. The helpers directory should contain any additional helpers that you create. Since geenee-rate is written with typescript, your helpers should be in typescript as well, with a .ts extension.

See this example for some ideas.

:computer: Adding Partials

You have access everywhere to the full list of partials in the partials directory. A partial is specified within a Handlebars file of the same name (not counting the file extension). You can add as many as you like, and create as many subdirectories as you need. But, there are two naming constraints:
1. The name of each partial must be unique.
2. Each partial file should have an '.hbs' extension.

This example shows some subdirectories and a number of examples. Many clauses that appear in multiple types of files are used.

:ledger: API

prepareHandlebars function

`
prepareHandlebars(projectDir: string)
`

Returns a handlebars with all the built-in and provided handlers and partials provided.

The projectDir is the path to a directory containing optional partials and handlers folders.

loadFileTemplate function


`
async function loadFileTemplate(
pathString: string,
Handlebars: any,
fileFilter: string|null, noFileInfo = false
)
`

The pathString tells where the template to load is stored. The file contains the contents of the template.

The Handlebars is a handlebars instance, typically created with prepareHandlebars.

You can optionally provide a fileFilter string to loadFileTemplate which is a glob. barbells will then prepare a template for use in with the geenee-rate generator by adding a geenee file info tag at the beginning of the template whenever a filename matches the fileFilter.

noFileInfo suppresses generation of a file info tag even if the filename matches the fileFilter`.

[//]: # ( ns__custom_end APIIntro )

[//]: # ( ns__custom_start constantsIntro )

[//]: # ( ns__custom_end constantsIntro )

[//]: # ( ns__start_section types )

[//]: # ( ns__end_section types )

[//]: # ( ns__end_section api )