Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/badsyntax/handlebars-form-helpers

Handlerbars.js form helpers
https://github.com/badsyntax/handlebars-form-helpers

Last synced: 11 months ago
JSON representation

Handlerbars.js form helpers

Awesome Lists containing this project

README 

          
# handlebars-form-helpers



[![Build Status](https://travis-ci.org/badsyntax/handlebars-form-helpers.png?branch=master)](https://travis-ci.org/badsyntax/handlebars-form-helpers)



A library of handlebars helpers that help with building forms.



## Installation



### Browser



1. Either [download](https://raw.github.com/badsyntax/handlebars-form-helpers/master/dist/handlebars.form-helpers.min.js) the

script, or install with [bower](http://bower.io/): `bower install handlebars-form-helpers`

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



    ```html

    

    

    ```



3. Register the helpers:



    ```javascript

    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:



    ```javascript

    var hbs = require('hbs');

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

    ```



### AMD



1. Either [download](https://raw.github.com/badsyntax/handlebars-form-helpers/master/dist/handlebars.form-helpers.min.js) the

script, or install with [bower](http://bower.io/): `bower install handlebars-form-helpers`

3. Load in the module and register it:



  ```javascript

  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:



```javascript

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}}

    {{this}}

{{/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:



```javascript

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**

```html

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

```

```html



```



**Label helper**

```html

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

```

```html

Please enter your name

```

```html

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

```

```html

Please enter your name

```



**Input helper**

```html

{{input "firstname" "Richard"}}

```

```html



```



**Button helper**

```html

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

```

```html

Submit form

```



**Submit button helper**

```html

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

```

```html

Submit form

```



**Select helper**

```html

{{select "title" titles title}}

```

```javascript

{

  titles: [{

    value: 'mr',

    text: 'Mr'

  }],

  title: 'mr'

}

```

```html

Mr

```



**Select (multiple) helper**

```html

{{select "title" titles selected}}

```

```javascript

{

  titles: [{

    value: 'mr',

    text: 'Mr'

  }],

  selected: ['mr']

}

```

```html

Mr

```



**Checkbox helper**

```html

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

```

```html



```



**File helper**

```html

{{file "fileupload"}}

```

```html



```



**Hidden helper**

```html

{{hidden "secret" "key123"}}

```

```html



```



**Password helper**

```html

{{password "password"}}

```

```html



```



**Textarea helper**

```html

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

```

```html

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:



```javascript

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:

// 

// Please enter a name');

```



### 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:



```javascript

var errors = {

  fieldName: [

    'Error message 1',

    'Error message 2!'

  ]

};

```



#### Examples:



**Input validation helper**

```html

{{input_validation "name" "" errors}}

```

```html



```



**Label validation helper**

```html

{{label_validation "name" "" errors}}

```

```html

Enter your name

```



**Select validation helper**

```html

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

```

```html

Mr

```



**Checkbox validation helper**

```html

{{checkbox_validation "title" 1 false errors}}

```

```html



```



**File validation helper**

```html

{{file_validation "fileupload" errors}}

```

```html



```



**Password validation helper**

```html

{{password_validation "password" "" errors}}

```

```html



```



**Textarea validation helper**

```html

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

```

```html

Here is some text

```



**Field errors helpers**



**Inline**

```

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

```

```html

Please enter some text


```

**Block**

```

{{#field_errors "text" errors}}

{{this}}

{{/field_errors}}

```

```html

Error message 1

Error 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](http://pivotal.github.io/jasmine/) for testing. If you want to run the tests, you'll need to have 

[nodejs](http://nodejs.org/), [grunt-cli](https://github.com/gruntjs/grunt-cli) and [bower](http://bower.io/) 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`.