Skip to content
Newer
Older
100644 336 lines (211 sloc) 8.96 KB
eea1606 @powmedia Docs
authored
1 backbone-forms
2 ==============
646f014 @powmedia first commit
authored
3
4 A form framework for Backbone.JS applications.
5
eea1606 @powmedia Docs
authored
6 The following default editors are included:
7
d3f6be7 @powmedia Rename TextField to Text
authored
8 - Text
eea1606 @powmedia Docs
authored
9 - Number
10 - Password
11 - TextArea
12 - Select
13 - Object
14 - NestedModel
15
16 In addition there is a separate file with editors that depend on jQuery UI:
17
18 - Date
19 - DateTime
299d401 @powmedia Docs
authored
20 - List (Editable and sortable. Can use any of the other editors for each item)
eea1606 @powmedia Docs
authored
21
22
23 Installation
24 ============
25
26 Requires BackboneJS and jQuery.
27
0b49de4 @powmedia Add CSS
authored
28 Include backbone-forms.js and backbone-forms.css:
eea1606 @powmedia Docs
authored
29
0b49de4 @powmedia Add CSS
authored
30 <link href="backbone-forms/backbone-forms.css" rel="stylesheet" type="text/css"/>
eea1606 @powmedia Docs
authored
31 <script src="backbone-forms/src/backbone-forms.js"></script>
32
33 Optionally, you can include the extra editors, for example those that require jQuery UI:
646f014 @powmedia first commit
authored
34
eea1606 @powmedia Docs
authored
35 <script src="backbone-forms/src/jquery-ui-editors.js"></script>
36
37
646f014 @powmedia first commit
authored
38 Usage
eea1606 @powmedia Docs
authored
39 =====
646f014 @powmedia first commit
authored
40
088e9f9 @powmedia Docs
authored
41 ![Example form](http://i56.tinypic.com/a3zfyt.png)
42
43 You can create something like the form above with the following steps:
44
37872a1 @powmedia Docs
authored
45 Define a 'schema' attribute on your Backbone models. The schema keys should match the attributes that get set on the model. Note that `type` defaults to `Text`.
646f014 @powmedia first commit
authored
46
47 var User = Backbone.Model.extend({
48 schema: {
088e9f9 @powmedia Docs
authored
49 start: { type: 'DateTime' },
50 contact: { type: 'Object', subSchema: {
51 name: {},
52 phone: {}
53 }}
37872a1 @powmedia Docs
authored
54 address: { type: 'NestedModel', model: Address },
088e9f9 @powmedia Docs
authored
55 notes: { type: 'List' }
646f014 @powmedia first commit
authored
56 }
57 });
58
59 Create the form in your Views:
088e9f9 @powmedia Docs
authored
60
646f014 @powmedia first commit
authored
61 var formView = Backbone.View.extend({
62 render: function() {
eea1606 @powmedia Docs
authored
63 var form = new Backbone.Form({
088e9f9 @powmedia Docs
authored
64 model: users.get(userId)
646f014 @powmedia first commit
authored
65 }).render();
66
67 $(this.el).append(form.el);
68
69 return this;
70 }
71 });
72
eea1606 @powmedia Docs
authored
73
646f014 @powmedia first commit
authored
74 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:
75
76 var errors = form.commit();
77
01b6fe8 @powmedia Docs
authored
78 To update a field after the form has been rendered, use `setValue`:
79
80 model.bind('change:name', function(model, name) {
81 form.fields.name.setValue(name);
82 });
4619643 @powmedia Docs
authored
83
646f014 @powmedia first commit
authored
84
eea1606 @powmedia Docs
authored
85 Usage without models
86 --------------------
87
88 You can create a form without tying it to a model. For example, to create a form for a simple object of data:
89
90 var form = new Backbone.Form({
91 data: { id: 123, name: 'Rod Kimble', password: 'cool beans' }, //Data to populate the form with
92 schema: {
37872a1 @powmedia Docs
authored
93 id: { type: 'Number' },
94 name: {},
95 password: { type: 'Password' }
eea1606 @powmedia Docs
authored
96 }
97 }).render();
98
99 Then instead of form.commit(), do:
100
101 var data = form.getValue(); //Returns object with new form values
102
103
646f014 @powmedia first commit
authored
104 Schema definition
eea1606 @powmedia Docs
authored
105 =================
646f014 @powmedia first commit
authored
106
eea1606 @powmedia Docs
authored
107 Main attributes
108 ---------------
646f014 @powmedia first commit
authored
109
eea1606 @powmedia Docs
authored
110 For each field definition in the schema you can use the following optional attributes:
646f014 @powmedia first commit
authored
111
eea1606 @powmedia Docs
authored
112 **`type`**
646f014 @powmedia first commit
authored
113
eea1606 @powmedia Docs
authored
114 - The editor to use in the field
37872a1 @powmedia Docs
authored
115 - Can be a string for any editor that has been added to Backbone.Form.editors, such as the built-in editors. E.g.: `{ type: 'TextArea' }`
eea1606 @powmedia Docs
authored
116 - Or can be a constructor function, e.g. for a custom editor: `{ type: MyEditor }`
d3f6be7 @powmedia Rename TextField to Text
authored
117 - If not defined, defaults to 'Text'
646f014 @powmedia first commit
authored
118
eea1606 @powmedia Docs
authored
119 **`title`**
646f014 @powmedia first commit
authored
120
37872a1 @powmedia Docs
authored
121 - Defines the text that appears in a form field's &lt;label&gt;
122 - If not defined, defaults to a formatted version of the camelCased field key. E.g. `firstName` becomes `First Name`. This behaviour can be changed by assigning your own function to Backbone.Form.helpers.keyToTitle.
646f014 @powmedia first commit
authored
123
124
eea1606 @powmedia Docs
authored
125 Editor-specific attributes
126 --------------------------
646f014 @powmedia first commit
authored
127
eea1606 @powmedia Docs
authored
128 If the schema `type` is one of the following, some extra schema attributes are required:
129
130 Select
131 ------
132
3708193 @powmedia Fix readme chars
authored
133 Creates and populates a &lt;select&gt; element.
eea1606 @powmedia Docs
authored
134
135 **`options`**
136
3708193 @powmedia Fix readme chars
authored
137 - Options to populate the &lt;select&gt;
eea1606 @powmedia Docs
authored
138 - Can be either:
3708193 @powmedia Fix readme chars
authored
139 - String of HTML &lt;option&gt;`s
37872a1 @powmedia Docs
authored
140 - Array of strings/numbers
eea1606 @powmedia Docs
authored
141 - Array of objects in the form `{ val: 123, label: 'Text' }`
142 - A Backbone collection
143 - A function that calls back with one of the above
144
145 Examples:
146
147 var schema = {
148 country: { 'Select', options: new CountryCollection() }
149 };
150
151 var schema = {
152 users: { 'Select', options: function(callback) {
153 users = db.getUsers();
154
155 callback(users);
156 }}
157 }
158
159 **Backbone collection notes**
3708193 @powmedia Fix readme chars
authored
160
161 If using a Backbone collection as the `option` attribute, models in the collection must implement a `toString()` method. This populates the label of the &lt;option&gt;. The ID of the model populates the `value` attribute.
eea1606 @powmedia Docs
authored
162
163 If there are no models in the collection, it will be `fetch()`ed.
164
165
166 Object
167 ------
168
169 The Object editor creates an embedded child form representing a Javascript object.
170
171 **`subSchema`**
172
173 - A schema object which defines the field schema for each attribute in the object
174
175 Examples:
176
177 var schema = {
178 address: { type: 'Object', subSchema: {
179 street: {},
180 zip: { type: 'Number' },
181 country: { 'Select', options: countries }
182 }}
183 };
184
185
186 NestedModel
187 -----------
188
37872a1 @powmedia Docs
authored
189 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), and keeps your schema cleaner.
646f014 @powmedia first commit
authored
190
eea1606 @powmedia Docs
authored
191 **`model`**
646f014 @powmedia first commit
authored
192
eea1606 @powmedia Docs
authored
193 - A reference to the constructor function for your nested model
37872a1 @powmedia Docs
authored
194 - The referenced model must have it's own `schema` attribute
eea1606 @powmedia Docs
authored
195
196 Examples:
197
198 var schema = {
199 address: { type: 'NestedModel', model: Address }
200 };
201
202
203 List
204 ----
205
37872a1 @powmedia Docs
authored
206 Creates a sortable and editable list of items, which can be any of the above schema types, e.g. Object, Number, Text etc. Currently requires jQuery UI for creating dialogs etc.
eea1606 @powmedia Docs
authored
207
208 **`listType`**
209
210 - Defines the editor that will be used for each item in the list.
211 - Similar in use to the main 'type' schema attribute.
d3f6be7 @powmedia Rename TextField to Text
authored
212 - Defaults to 'Text'
213
45df2ee @powmedia Docs
authored
214 **`itemToString`**
f74af4b @powmedia Docs
authored
215
216 - Optional, but recommended when using listType 'Object'
217 - A function that returns a string representing how the object should be displayed in a list item.
9128501 @powmedia Add option to disable sorting on List editor
authored
218 - When listType is 'NestedModel', the model's `toString()` method will be used, unless a specific `itemToString()` function is defined on the schema.
219
220 **`sortable`**
221
222 - Optional. Set to false to disable drag and drop sorting
223
f74af4b @powmedia Docs
authored
224
225 Examples:
226
227 var schema = {
45df2ee @powmedia Docs
authored
228 users: { type: 'List', listType: 'Object', itemToString: function(user) {
f74af4b @powmedia Docs
authored
229 return user.firstName + ' ' + user.lastName;
230 }
231 }
232 };
d3f6be7 @powmedia Rename TextField to Text
authored
233
234
235
236 Form options
237 ============
238
239 **`model`**
240
241 The model to tie the form to. Calling `form.commit()` will update the model with new values.
242
243 **`data`**
244
245 If not using the `model` option, pass a native object through the `data` option. Then use `form.getValue()` to get the new values.
246
247 **`schema`**
248
249 The schema to use to create the form. Pass it in if you don't want to store the schema on the model, or to override the model schema.
250
1667923 @powmedia Docs
authored
251 **`fields`**
252
253 An array of field names (keys). Only the fields defined here will be added to the form. You can also use this to re-order the fields.
254
d3f6be7 @powmedia Rename TextField to Text
authored
255 **`idPrefix`**
256
257 A string that will be prefixed to the form DOM element IDs. Useful if you will have multiple forms on the same page. E.g. `idPrefix: 'user-'` will result in IDs like 'user-name', 'user-email', etc.
258
259
260
261 Editors without forms
262 =====================
263
264 You can add editors by themselves, without being part of a form. For example:
265
266 var select = new Backbone.Form.editors.Select({
267 model: user,
268 key: 'country',
269 options: getCountries()
270 }).render();
271
272 //When done, apply selection to model:
273 select.commit();
eea1606 @powmedia Docs
authored
274
275
276 Custom Editors
277 ==============
278
279 Custom editors can be written. They must extend from Backbone.Form.editors.Base.
280
281 var CustomEditor = Backbone.Form.editors.Base.extend({
646f014 @powmedia first commit
authored
282
283 tagName: 'input',
284
285 initialize: function(options) {
286 //Call parent constructor
eea1606 @powmedia Docs
authored
287 Backbone.Form.editors.Base.prototype.initialize.call(this, options);
646f014 @powmedia first commit
authored
288
289 //Custom setup code.
290 if (this.schema.customParam) this.doSomething();
291 },
292
293 render: function() {
4619643 @powmedia Docs
authored
294 this.setValue(this.value);
646f014 @powmedia first commit
authored
295
296 return this;
297 },
298
299 getValue: function() {
300 return $(this.el).val();
4619643 @powmedia Docs
authored
301 },
302
303 setValue: function(value) {
304 $(this.el).val(this.value);
646f014 @powmedia first commit
authored
305 }
306
307 });
308
eea1606 @powmedia Docs
authored
309 **Notes:**
3708193 @powmedia Fix readme chars
authored
310
4619643 @powmedia Docs
authored
311 - The editor must implement a getValue() and setValue().
646f014 @powmedia first commit
authored
312 - The original value is available through this.value.
313 - The field schema can be accessed via this.schema. This allows you to pass in custom parameters.
314
315
316 Defaults & Validation
eea1606 @powmedia Docs
authored
317 =====================
646f014 @powmedia first commit
authored
318
319 Formal uses the built in Backbone validation and defaults as defined on the model.
320
321 For validation, it will attempt to update the model and if there are validation failures, it will report them back.
322
323 See the Backbone documentation for more details.
324
325
ae98167 @powmedia Add known issues
authored
326 Known issues
327 ============
328
43e9275 @powmedia Fix List NestedModel not updating display after edit/add
authored
329 - List editor with listType NestedModel doesn't run validation
088e9f9 @powmedia Docs
authored
330 - There may be CSS issues across browsers. You can customise your CSS by editing the backbone-forms.css file.
ae98167 @powmedia Add known issues
authored
331
646f014 @powmedia first commit
authored
332 Contributors
eea1606 @powmedia Docs
authored
333 ============
646f014 @powmedia first commit
authored
334
335 - Charles Davison - [powmedia](http://github.com/powmedia)
Something went wrong with that request. Please try again.