handlebars-form-helpers
A library of handlebars helpers that help with building forms.
Installation
Browser
-
Either download the script, or install with bower:
bower install handlebars-form-helpers
-
Load the scripts into your page. (It does not matter which order the scripts are loaded in.)
-
Register the helpers:
HandlebarsFormHelpers;
Node/CommonJS
-
You can install the helpers with npm:
npm install handlebars-form-helpers
-
Load in the module and register it:
var hbs = ;;
AMD
- Either download the
script, or install with bower:
bower install handlebars-form-helpers
- Load in the module and register it:
;
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;
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
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}}
Label helper
{{label "name" "Please enter your name"}}
Please enter your name
{{#label}}Please enter your name{{/label}}
Please enter your name
Input helper
{{input "firstname" "Richard"}}
Button helper
{{button "save" "Submit form"}}
Submit form
Submit button helper
{{submit "save" "Submit form"}}
Submit form
Select helper
{{select "title" titles title}}
titles: value: 'mr' text: 'Mr' title: 'mr'
Mr
Select (multiple) helper
{{select "title" titles selected}}
titles: value: 'mr' text: 'Mr' selected: 'mr'
Mr
Checkbox helper
{{checkbox "apples" "yes" true}}
File helper
{{file "fileupload"}}
Hidden helper
{{hidden "secret" "key123"}}
Password helper
{{password "password"}}
Textarea helper
{{textarea "text" "Here is some text"}}
Here is some text
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;var html = ; // 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}}
Label validation helper
{{label_validation "name" "" errors}}
Enter your name
Select validation helper
{{select_validation "title" titles "" errors}}
Mr
Checkbox validation helper
{{checkbox_validation "title" 1 false errors}}
File validation helper
{{file_validation "fileupload" errors}}
Password validation helper
{{password_validation "password" "" errors}}
Textarea validation helper
{{textarea_validation "text" "Here is some text" errors}}
Here is some text
Field errors helpers
Inline
{{field_errors "text" errors class="error"}}
Please enter some text
Block
{{#field_errors "text" errors}}
<span class="help-block">{{this}}</span>
{{/field_errors}}
Error message 1Error message 2
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
.