handlebars-form-helpers

A library of handlebars helpers that help with building forms.

Installation

Browser

1. Either download the script, or install with bower: bower install handlebars-form-helpers

2. Load the scripts into your page. (It does not matter which order the scripts are loaded in.)

   <script src="handlebars.js"></script>
   <script src="handlebars.form-helpers.js"></script>

3. Register the helpers:

   HandlebarsFormHelpers.register(Handlebars);

Node/CommonJS

1. You can install the helpers with npm: npm install handlebars-form-helpers

2. Load in the module and register it:

   var hbs = require('hbs');
   require('handlebars-form-helpers').register(hbs.handlebars);

AMD

1. Either download the script, or install with bower: bower install handlebars-form-helpers
2. Load in the module and register it:

define(['handlebars', 'handlebars-form-helpers'], function(Handlebars, HandlebarsFormHelpers) {
    HandlebarsFormHelpers.register(Handlebars);
    // ..etc
});

Usage

Registering the helpers

You have to register the helpers before you can use them in your templates. The register method expects the Handlebars object to be passed in, and an optional config object, for example:

HandlebarsFormHelpers.register(Handlebars, {
  namespace: 'custom',
  validationErrorClass: 'custom-validation-class'
});

Once the helpers are registered, you can use the helpers in your templates, and compile your templates as you usually would.

Using the helpers

Most of the helpers can be used inline, for example:

{{label "name" "Please enter your name"}}

The only block helpers are the form, label and field_errors helpers:

{{#form "/post" class="form"}} ... {{/form}}
{{#label}}
    A field label
{{/label}}
{{#field_errors "surname" errors}}
    <span class="help-block">{{this}}</span>
{{/field_errors}}`

By default the helpers are registered without a namespace. This gives you short and friendly helper names.

If you need to change the helpers namespace, you can specify a custom namespace when registering the helpers, for example:

HandlebarsFormHelpers.register(Handlebars, {
  namespace: 'myform'
})

Now the helpers are created with that namespace, for example:

{{myform-label "name" "Please enter your name"}}

Common form helpers

{{#form url class="form"}}{{/form}}
{{label "name" "Please enter your name"}}
{{input "firstname" person.name}}
{{button "save" "Submit form"}}
{{submit "save" "Submit form"}}
{{select "title" titles person.title}}
{{checkbox "apples" "yes" true}}
{{file "fileupload"}}
{{hidden "secret" "key123"}}
{{password "password"}}
{{textarea "text" "Here is some text"}}

Examples:

Form helper

{{#form "/contact" class="form"}}{{/form}}

<form method="POST" action="/contact" class="form"></form>

Label helper

{{label "name" "Please enter your name"}}

<label for="name">Please enter your name</label>

{{#label}}Please enter your name{{/label}}

<label>Please enter your name</label>

Input helper

{{input "firstname" "Richard"}}

<input type="text" id="firstname" name="firstname" value="Richard" />

Button helper

{{button "save" "Submit form"}}

<button name="save" type="button">Submit form</button>

Submit button helper

{{submit "save" "Submit form"}}

<button name="save" type="submit">Submit form</button>

Select helper

{{select "title" titles title}}

{
  titles: [{
    value: 'mr',
    text: 'Mr'
  }],
  title: 'mr'
}

<select id="title" name="title"><option value="mr" selected="selected">Mr</option></select>

Select (multiple) helper

{{select "title" titles selected}}

{
  titles: [{
    value: 'mr',
    text: 'Mr'
  }],
  selected: ['mr']
}

<select id="title" name="title" multiple="true"><option value="mr" selected="selected">Mr</option></select>

Checkbox helper

{{checkbox "apples" "yes" true}}

<input id="apples" name="apples" type="checkbox" value="yes" checked="true" />

File helper

{{file "fileupload"}}

<input name="fileupload" id="fileupload" type="file" />

Hidden helper

{{hidden "secret" "key123"}}

<input name="secret" id="secret" value="key123" type="hidden" />

Password helper

{{password "password"}}

<input name="password" id="password" type="password" />

Textarea helper

{{textarea "text" "Here is some text"}}

<textarea name="text" id="text">Here is some text</textarea>

Form validation helpers

Validation helpers work in a similar way to the common form helpers, but handle displaying of validation errors and field error styling.

The validation helpers expect an 'errors' object to be passed in, which is used to display the validation errors for the field.

For example:

var data = {
  errors: {
    name: [
      'Please enter a name'
    ]
  }
};
var source = '{{input_validation "name" "" errors}}' +
    '{{field_errors "name" errors class="help-block text-error"}}';
var template = Handlebars.compile(source);
var html = template(data);

// Compiled HTML will be:
// <input name="name" id="name" type="text" class="validation-error" />
// <span class="help-block text-error">Please enter a name</span>');

Validation helpers

{{input_validation "firstname" person.name errors}}
{{label_validation "name" "Please enter your name" errors}}
{{select_validation "title" titles person.title errors}}
{{checkbox_validation "food[]" "apples" true errors}}
{{file_validation "fileupload" errors}}
{{password_validation "password" "dontdothis" errors}}
{{textarea_validation "text" "Here is some text" errors}}

Error data

The errors object has to be in the following format:

var errors = {
  fieldName: [
    'Error message 1',
    'Error message 2!'
  ]
};

Examples:

Input validation helper

{{input_validation "name" "" errors}}

<input name="name" id="name" type="text" class="validation-error" />

Label validation helper

{{label_validation "name" "" errors}}

<label for="name" class="validation-error">Enter your name</label>

Select validation helper

{{select_validation "title" titles "" errors}}

<select id="title" name="title" class="validation-error"><option value="mr">Mr</option></select>

Checkbox validation helper

{{checkbox_validation "title" 1 false errors}}

<input name="title" type="checkbox" value="1" id="title" class="validation-error" />

File validation helper

{{file_validation "fileupload" errors}}

<input name="fileupload" id="fileupload" type="file" class="validation-error" />

Password validation helper

{{password_validation "password" "" errors}}

<input name="password" id="password" type="password" class="validation-error" />

Textarea validation helper

{{textarea_validation "text" "Here is some text" errors}}

<textarea name="text" id="text" class="validation-error">Here is some text</textarea>

Field errors helpers

Inline

{{field_errors "text" errors class="error"}}

<div class="error">Please enter some text</div>

Block

{{#field_errors "text" errors}}
<span class="help-block">{{this}}</span>
{{/field_errors}}

<span class="help-block">Error message 1</span>
<span class="help-block">Error message 2</span>

Demo

This demo shows how to use the helpers to build a form that handles validation: http://badsyntax.github.io/handlebars-form-helpers/

Contributing

Feel free to send pull requests.

Running the tests

This project uses jasmine for testing. If you want to run the tests, you'll need to have nodejs, grunt-cli and bower installed. You'll also need to install the project dependencies by running npm install && bower install in the project root.

Once everything is installed, you can run the tests by either running npm test or grunt test.