A form framework for Backbone.JS applications.
The following default editors are included:
- TextField
- Number
- Password
- TextArea
- Select
- Object
- NestedModel
In addition there is a separate file with editors that depend on jQuery UI:
- Date
- DateTime
- List
Requires BackboneJS and jQuery.
Include backbone-forms.js:
<script src="backbone-forms/src/backbone-forms.js"></script>
Optionally, you can include the extra editors, for example those that require jQuery UI:
<script src="backbone-forms/src/jquery-ui-editors.js"></script>
Define a 'schema' attribute on your Backbone models. The schema keys should match the attributes that get set on the model.
var User = Backbone.Model.extend({
schema: {
id: { type: 'Number' },
name: {},
address: { type: 'NestedModel' },
email: {title: 'Email address' },
password: { type: 'Password' }
}
});
Create the form in your Views:
var formView = Backbone.View.extend({
render: function() {
var form = new Backbone.Form({
model: this.model
}).render();
$(this.el).append(form.el);
return this;
}
});
You can include selected fields, in custom order with the 'fields' parameter:
var form = new Backbone.Form({
model: this.model,
fields: ['name', 'email', 'address']
});
Once the user is done with the form, call commit() to apply the updated values to the model. If there are validation errors they will be returned:
var errors = form.commit();
You can create a form without tying it to a model. For example, to create a form for a simple object of data:
var form = new Backbone.Form({
data: { id: 123, name: 'Rod Kimble', password: 'cool beans' }, //Data to populate the form with
schema: {
id: { type: 'Number' },
name: {},
password: { type: 'Password' }
}
}).render();
Then instead of form.commit(), do:
var data = form.getValue(); //Returns object with new form values
For each field definition in the schema you can use the following optional attributes:
type
- The editor to use in the field
- Can be a string e.g.:
{ type: 'TextArea' }
- Or can be a constructor function, e.g. for a custom editor:
{ type: MyEditor }
- If not defined, defaults to 'TextField'
title
- Defines the text that appears in a form field's
<label>
- If not defined, defaults to a formatted version of the camelCased field key. E.g.
firstName
becomesFirst Name
If the schema type
is one of the following, some extra schema attributes are required:
Creates and populates a <select>
element.
options
- Options to populate the
<select>
- Can be either:
- String of HTML
<option>
s - Array of items
- Array of objects in the form
{ val: 123, label: 'Text' }
- A Backbone collection
- A function that calls back with one of the above
- String of HTML
Examples:
var schema = {
country: { 'Select', options: new CountryCollection() }
};
var schema = {
users: { 'Select', options: function(callback) {
users = db.getUsers();
callback(users);
}}
}
Backbone collection notes
If using a Backbone collection as the option
attribute, models in the collection must implement a toString()
method. This populates the label of the <option>
. The ID of the model populates the value
attribute.
If there are no models in the collection, it will be fetch()
ed.
The Object editor creates an embedded child form representing a Javascript object.
subSchema
- A schema object which defines the field schema for each attribute in the object
Examples:
var schema = {
address: { type: 'Object', subSchema: {
street: {},
zip: { type: 'Number' },
country: { 'Select', options: countries }
}}
};
Used to embed models within models. Similar to the Object editor, but adds validation of the child form (if it is defined on the model).
model
- A reference to the constructor function for your nested model
Examples:
var schema = {
address: { type: 'NestedModel', model: Address }
};
Creates a sortable and editable list of items, which can be any of the above schema types, e.g. Object, Number, TextField etc.
(Requires jQuery UI)
listType
- Defines the editor that will be used for each item in the list.
- Similar in use to the main 'type' schema attribute.
- Defaults to 'TextField'
Custom editors can be written. They must extend from Backbone.Form.editors.Base.
var CustomEditor = Backbone.Form.editors.Base.extend({
tagName: 'input',
initialize: function(options) {
//Call parent constructor
Backbone.Form.editors.Base.prototype.initialize.call(this, options);
//Custom setup code.
if (this.schema.customParam) this.doSomething();
},
render: function() {
$(this.el).val(this.value);
return this;
},
getValue: function() {
return $(this.el).val();
}
});
Notes:
- The editor must implement a getValue().
- The original value is available through this.value.
- The field schema can be accessed via this.schema. This allows you to pass in custom parameters.
Formal uses the built in Backbone validation and defaults as defined on the model.
For validation, it will attempt to update the model and if there are validation failures, it will report them back.
See the Backbone documentation for more details.
- Charles Davison - powmedia