retro/formbinder

Form builder for JavaScriptMVC with automatic binding to a model

FormBinder

FormBinder is a form builder for JavaScriptMVC with automatic binding to a model. It is inspired by the SimpleForm library for Rails.

It provides a builder for your forms and it binds that form to a model instance. That way you can implement live validation for your form in a model.

Installation

You can install this plugin by either checking out the repo, or by downloading the code as an archive. If you're checking out the repo, make sure that you check it out in the form_binder folder instead of FormBinder:

git checkout [email protected]:retro/FormBinder.git form_binder

When you want to use the plugin you have to steal it from your controller:

steal('form_binder', ....).then();

If you don't put FormBinder in your steal.root directory (one where the jquery, funcunit, steal, etc., folders are) you have to steal it by using path to the folder. For instance if you put it inside of ROOT_JS_DIRECTORY/my_app/form_binder you would steal it like this:

steal('my_app/form_binder', ....).then();

Usage

FormBinder can inspect Model's attributes property and automatically build form from that.

If you have a model that looks like this:

$.Model.extend("BlogPost",{
  attributes : { 
    title : 'string',
    lead   : 'text',
  }
}, {});

You can build your form like this:

<% var f = form_builder(model_instance) // You can pass this variable from controller %>
<form <%= f.bindForm %>>
  <%= f.inputs(); %>
  <input type="submit" value="Submit form" />
</form>

It will create fields for title and lead. Title will be rendered as a text input and lead as a textarea.

You can pass FormBuilder object from controller by instantiating it like this

var f = FormBinder.Builder.getBuilder(model_instance);

If you need more customization you can render each field on it's own:

<% var f = form_builder(model_instance) // You can pass this variable from controller %>
<form <%= f.bindForm %>>
  <%= f.input('title'); %>
  <%= f.input('lead'); %>
  <input type="submit" value="Submit form" />
</form>

Customization

You can customize rendering of your fields by passing options to the input method:

<form <%= f.bindForm %>>
  <%= f.input('title', {as: 'textarea', label: 'Insert title', hint: 'Blog title'}); %>
  <input type="submit" value="Submit form" />
</form>

FormBinder currently supports following field types:

• string - renders as a text input
• password
• textarea
• boolean - renders as a checkbox
• checkboxGroup
• radioGroup
• select

If you want to provide available values to a radio group, a check box group or a select input there are two ways to do it. By default FormBinder's builder will look for a valuesForField class method on a Model:

$.Model.extend("BlogPost",{
  attributes: {
    status: 'string'
  },
  valuesForStatus: [['published', 'Published'], ['draft', 'Draft']]
}, {});

You can also provide values inline in template:

<%= f.input('status', {as: 'select', values: [['published', 'Published'], ['draft', 'Draft']]}) %>

Changing Input or Wrapper templates

FormBinder can load your custom field or wrapper templates. All you need to do is pass it as option to the FormBinder.Builder. Supported options are:

// Wrappers
generic_wrapper                : 'views/wrappers/generic.ejs',
boolean_checkbox_radio_wrapper : 'views/wrappers/boolean_checkbox_radio.ejs',

// Inputs
boolean_input        : 'views/inputs/boolean.ejs',
checkbox_group_input : 'views/inputs/checkbox_group.ejs',
password_input       : 'views/inputs/password.ejs',
radio_group_input    : 'views/inputs/radio_group.ejs',
select_input         : 'views/inputs/select.ejs',
string_input         : 'views/inputs/string.ejs',
textarea_input       : 'views/inputs/textarea.ejs'

If you wanted to change string_input's location you can initialize FormBinder.Builder like this:

<% var f = form_builder(model_instance, {string_input: "My/location/of/string/input"}) %>

or

var f = FormBinder.Builder.getBuilder(model_instance, {string_input: "My/location/of/string/input"});

Supported Versions and License

FormBinder works with the 3.2.1 and edge versions of JavaScriptMVC.

FormBinder is published under MIT License.

formbinder's Issues

add install section to the Readme

Could you add an install section to the Readme? I'm new to Javascript MVC and this is the first plug-in I will be using.

JSMVC v3.1 : bindForm() hookup is broken on form element

the functional tests only pass when hooking up a div wrapper around the form element, otherwhise the controller is set on the first input element generated by $.View in the FormBinderBuilder class.

$.View() does't look to path relative to current file

in form_binder_builder.js, you use a lot $.View(aPath) to render template files

On my JSMVC 3.1 env, the app try to load http://host/currentWebpage/theViewPathAsked instead of the proper file,

I'm a newbee to jsmvc so this is perhaps a trivial param i didn't set (related to how the plugin is stealed), could you let me know if this is the case ?

Meanwhile i fixed that with an uggly variable defined outside the class :\