barbells

simple management of helpers and partials for handlebars

• :clipboard: Why
• :white_check_mark: What
• :wrench: Basic Usage
• :paperclip: Built In Handlers
• :thumbsup: Adding Helpers
• :waxing_gibbous_moon: Adding Partials
• :cyclone: 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 standard 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.

1. 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.
   • {{curly true}} produces a left curly brace {, {{curly false}} returns }.

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

:thumbsup: Adding Helpers

1. 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.

:waxing_gibbous_moon: 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.

:cyclone: 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.