Skip to content
Newer
Older
100644 664 lines (475 sloc) 21.2 KB
6a05460 @derickbailey minified and updated readme
derickbailey authored
1 # About Backbone.ModelBinding
2
3 Convention-based, awesome model binding for [Backbone.js](http://documentcloud.github.com/backbone),
4 inspired by [Brad Phelan](http://xtargets.com/2011/06/11/binding-model-attributes-to-form-elements-with-backbone-js/),
5 [Knockout.js](http://knockoutjs.com/) ' data-binding capabilities,
6 and [Brandon Satrom](http://userinexperience.com/?p=633)'s work with Knockout.
7
8 This plugin provides a simple, convention based mechanism to create bi-directional
9 binding between your HTML form input elements and your Backbone models.
10
11 Instead of writing the same boiler plate code to read from your form inputs and
12 populate the model attributes, for every input on your form, you can make a
13 single call to `Backbone.ModelBinding.bind(myView)` and have all of your inputs
14 automatically wired up. Any change you make to a forn input will populate a
15 corresponding model attribute for you. The binding is bi-directional, as well.
16 This means that changes to your underlying model will be propagated to your
17 form inputs without having to manually bind to your model's `change` events.
18
19 If you're looking for Knockout.js-style `data-bind` attributes, for Backbone,
20 then this is the plugin for you. Backbone.ModelBinding provides some very basic
21 support for `data-bind` attributes, allowing your Backbone model `change` events
22 to modify nearly any HTML element on your page. Whether it's updating the text
23 of a `<div>`, or changing the css class of an `<img>` tag, the `data-bind`
24 support provides a very powerful and flexible means of creating a very rich
25 user experience.
153f007 @derickbailey link to blog post that inspired this
derickbailey authored
26
004fd10 @derickbailey updating readme with example and cautionary info
derickbailey authored
27 ## Getting Started
000549a @derickbailey note on not being ready for use
derickbailey authored
28
dfc805a @derickbailey updating readme with info about prerequisites, etc
derickbailey authored
29 It's easy to get up and running. You only need to have Backbone (including underscore.js -
30 a requirement for Backbone) and jQuery in your page before including the backbone.modelbining
31 plugin.
000549a @derickbailey note on not being ready for use
derickbailey authored
32
dfc805a @derickbailey updating readme with info about prerequisites, etc
derickbailey authored
33 ### Prerequisites
34
35 * Backbone.js v0.5.1 or higher
36 * jQuery v1.6.2 or higher
37
38 This is a plugin for Backbone.js and is built and tested against Backbone v0.5.1. It also uses jQuery
39 to perform most of the bindng and manipulations, and is built and tested against v1.6.1. However, I am
40 currently using this plugin in a production application with Backbone v0.3.3 and jQuery v1.5.1.
41
42 At this point, I make no guarantees of it working with any version of Backbone or jQuery,
43 other than what it has been built and tested against. It works for me, so it may work for you
44 with versions other than what is stated
45
46 ### Get The ModelBinding Plugin
47
48 Download the `backbone.modelbinding.js` file from this github repository and copy it into
49 your javascripts folder. Add the needed `<script>` tag to bring the plugin into any page
50 that wishes to use it. Be sure to include the modelbinding file _after_ the backbone.js file.
51
2c8eb06 @derickbailey documentation for unbind method
derickbailey authored
52 ### Model Binding
7f2301e @derickbailey added basic support for htmlBindings - to go from the model's fields …
derickbailey authored
53
2c8eb06 @derickbailey documentation for unbind method
derickbailey authored
54 The model binding code is executed with a call to `Backbone.ModelBinding.bind(view)`. There are
8755836 @derickbailey updated the documentation concerning when to call the model binding code
derickbailey authored
55 several places that it can be called from, depending on your circumstances.
56
57 All of the element binding happens within the context of the view's `el`, therefore you must
58 call the model binding code after your view's `el` has been populated with the elements that
59 will be bound to.
60
61 #### Binding After Rendering
62
63 If your view modifies the html contents of the view's `el` in the `render` method, you should
64 call the model binding after the modifications are made:
004fd10 @derickbailey updating readme with example and cautionary info
derickbailey authored
65
66 ````
67 SomeView = Backbone.View.extend({
7f2301e @derickbailey added basic support for htmlBindings - to go from the model's fields …
derickbailey authored
68 render: function(){
69 // ... render your form here
8755836 @derickbailey updated the documentation concerning when to call the model binding code
derickbailey authored
70 $(this.el).html("... some html and content goes here ... ");
7f2301e @derickbailey added basic support for htmlBindings - to go from the model's fields …
derickbailey authored
71
8755836 @derickbailey updated the documentation concerning when to call the model binding code
derickbailey authored
72 // execute the model bindings
2c8eb06 @derickbailey documentation for unbind method
derickbailey authored
73 Backbone.ModelBinding.bind(this);
004fd10 @derickbailey updating readme with example and cautionary info
derickbailey authored
74 }
75 });
76 ````
77
8755836 @derickbailey updated the documentation concerning when to call the model binding code
derickbailey authored
78 #### Binding A View That Does Not Render
79
80 If, however, your view has an `el` that represents an existing element in your html, and the
81 contents of the `el` are not modified during a call to `render`, then you can make the call to
82 the model binding code in the initializer or anywhere else.
83
84 ````
85 <form id="some-form">
86 Name: <input id="name">
87 </form>
88 ````
89
90 ````
91 FormView = Backbone.View.extend({
92 el: "#some-form",
93
94 initialize: function(){
2c8eb06 @derickbailey documentation for unbind method
derickbailey authored
95 Backbone.ModelBinding.bind(this);
8755836 @derickbailey updated the documentation concerning when to call the model binding code
derickbailey authored
96 }
97 });
98 ````
99
100 #### Binding From Outside A View
101
102 There is no requirement for the model binding code to be called from within a view directly.
103 You can bind the view from external code, like this:
104
105 ````
106 FormView = Backbone.View.extend({
107 el: "#some-form",
108 });
109
110 formView = new FormView();
2c8eb06 @derickbailey documentation for unbind method
derickbailey authored
111 Backbone.ModelBinding.bind(formView);
112 ````
113
114 ### Model Unbinding
115
116 When your view has completed its work and is ready to be removed from the DOM, you not only
117 need to unbnd your view's events (handled through the view's `remove` method, typically), you
118 also need to unbind the model events that are bound in the view.
119
120 Backbone.ModelBinding can unbind its own events through a simple call to
121 `Backbone.ModelBinding.unbind(view)`. If you do not call this method when your view is being
122 closed / removed / cleaned up, then you may end up with memory leaks and zombie views that
123 are still responding to model change events.
124
125 ````
126 FormView = Backbone.View.extend({
127 el: "#some-form",
128
129 initialize: function(){
130 Backbone.ModelBinding.bind(this);
131 },
132
133 close: function(){
134 this.remove();
135 this.unbind();
136 Backbone.ModelBinding.unbind(this);
137 }
138 });
8755836 @derickbailey updated the documentation concerning when to call the model binding code
derickbailey authored
139 ````
140
47e4cbc @derickbailey updated the readme to talk about the configuration options for the co…
derickbailey authored
141 ## Convention Bindings
e4932c6 @derickbailey updated readme to talk about convention binding
derickbailey authored
142
143 Automatic bi-directional binding between your form input and your model.
144
145 The convention based binding requires no additional configuration or code in your
2c8eb06 @derickbailey documentation for unbind method
derickbailey authored
146 view, other than calling the `Backbone.ModelBinding.bind(this);` as noted above.
e4932c6 @derickbailey updated readme to talk about convention binding
derickbailey authored
147 With the conventions binding, your `<input>` fields will be bound to the views model
148 by the id of the input.
149
150 For example:
151
152 ````
153 // something.html
154
155 <input id='name'>
156
157 // something.js
158
159 SomeModel = Backbone.Model.extend();
160
161 SomeView = Backbone.View.extend({
162 render: function(){
163 // ... render your form here
164
165 // execute the defined bindings
2c8eb06 @derickbailey documentation for unbind method
derickbailey authored
166 Backbone.ModelBinding.bind(this);
e4932c6 @derickbailey updated readme to talk about convention binding
derickbailey authored
167 }
168 });
169
170 model = new SomeModel();
171 view = new SomeView({model: model});
172
173 model.set({name: "some name"});
174
175 ````
176
177 In this example, when `model.set` is called to set the name, "some name" will appear
178 in the `#name` input field. Similarly, when the `#name` input field is changed, the
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
179 value entered into that field will be sent to the model's `name` property.
e4932c6 @derickbailey updated readme to talk about convention binding
derickbailey authored
180
bb8d234 @derickbailey documented data-bind
derickbailey authored
181 ## Data-Bind Attributes
57ed5b9 @derickbailey updated docs to list supported input types
derickbailey authored
182
bb8d234 @derickbailey documented data-bind
derickbailey authored
183 Backbone.ModelBinding supports Knockout-style data-bind attributes on any arbitrary
184 HTML element. These bindings will populate any attribute, the text, or HTML contents
185 of an HTML element based on your configurations. This is particularly useful when a
186 model that is being edited is also being displayed elsewhere on the screen.
187
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
188 To bind an element to a model's properties, add a `data-bind` attribute to the element
189 and specify what should be updated with which model property using a `elementAttr modelAttr`
bb8d234 @derickbailey documented data-bind
derickbailey authored
190 format. For example `<span data-bind="text name">` will update the span's text with
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
191 the model's name property, when the model's name changes.
bb8d234 @derickbailey documented data-bind
derickbailey authored
192
193 ````
194 <form>
195 <input type="text" id="name">
196 </form>
197 Name: <span data-bind="text name">
198
199 SomeView = Backbone.View.extend({
200 // ...
201
202 render: function(){
203 // ...
2c8eb06 @derickbailey documentation for unbind method
derickbailey authored
204 Backbone.ModelBinding.bind(this);
bb8d234 @derickbailey documented data-bind
derickbailey authored
205 }
206 });
207
208 someModel = new SomeModel();
209 someView = new SomeView({model: someModel});
210 ````
211
212 In this example, the model's `name` will be updated when you type into the text box
213 and then tab or click away from it (to fire the change event). When the model's `name`
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
214 property is updated, the `data-bind` convention will pick up the change and set
bb8d234 @derickbailey documented data-bind
derickbailey authored
215 the text of the `span` to the model's name.
216
b5e4c0c @derickbailey updated readme and release note for v0.3.7's multiple data-bind
derickbailey authored
217 ### Data-Bind Multiple Attributes
218
219 Multiple attributes can be specified for a single element's `data-bind` by separating
220 each with a `;` (semi-colon). For example:
221
222 ````
223 <form>
224 <input type="text" id="name">
225 </form>
226 Name: <span data-bind="text name; class name">
227
228 SomeView = Backbone.View.extend({
229 // ...
230
231 render: function(){
232 // ...
233 Backbone.ModelBinding.bind(this);
234 }
235 });
236
237 someModel = new SomeModel();
238 someView = new SomeView({model: someModel});
239 ````
240
241 In this example, both the text and the css class will be updated when you change
242 the name input. You can data-bind as many attributes as you need, in this manner.
243
977f674 @derickbailey docs for data-bind='enabled ...' and spec to prove data-bind='disable…
derickbailey authored
244 ### Special Cases For data-bind
245
246 There are several special cases for the data-bind attribute. These allow a little more
247 functionality than just setting an attribute on an element.
248
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
249 * (default) - if you only specify the model property, defaults to the text of the html element
977f674 @derickbailey docs for data-bind='enabled ...' and spec to prove data-bind='disable…
derickbailey authored
250 * text - replace the text contents of the element
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
251 * html - replace the html contents of the element
977f674 @derickbailey docs for data-bind='enabled ...' and spec to prove data-bind='disable…
derickbailey authored
252 * enabled - enable or disable the html element
253
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
254 #### (default)
977f674 @derickbailey docs for data-bind='enabled ...' and spec to prove data-bind='disable…
derickbailey authored
255
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
256 If you only specify the model's property in the data-bind attribute, then the data-bind
257 will bind the value of that model property to the `text` of the html element.
977f674 @derickbailey docs for data-bind='enabled ...' and spec to prove data-bind='disable…
derickbailey authored
258
259 ````
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
260 <div data-bind="name"/>
977f674 @derickbailey docs for data-bind='enabled ...' and spec to prove data-bind='disable…
derickbailey authored
261 ````
262
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
263 See the document for data-bind text, below.
264
977f674 @derickbailey docs for data-bind='enabled ...' and spec to prove data-bind='disable…
derickbailey authored
265 #### text
266
267 If you set the data-bind attribute to use `text`, it will replace the text contents of the
268 html element instead of just setting an element attribute.
269
270 ````
271 <div id="someDiv" data-bind="text someProperty"></div>
272
273
274 someModel.set({someProperty: "some value"});
275 ````
276
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
277 #### html
278
279 If you set the data-bind attribute to use `html`, it will replace the entire
280 inner html of the html element, instead of just setting an element attribute.
281
282 ````
283 <div id="someDiv" data-bind="html someProperty"></div>
284
285
286 someModel.set({someProperty: "some value"});
287 ````
288
977f674 @derickbailey docs for data-bind='enabled ...' and spec to prove data-bind='disable…
derickbailey authored
289 #### enabled
290
291 This special case breaks the html element standard of using a `disabled` attribute, specifically
292 to inver the logic used for enabling / disabling an element, to keep the data-bind attribute
293 clean and easy to read.
294
295 If you have a model with a property that indicates a negative state, such as `invalid`, then you
296 can use a data-bind attribute of `disabled`:
297
298 ````
299 <button id="someButton" data-bind="disabled invalid"></div>
300
301
302 someModel.set({invalid: true});
303 ````
304
305 However, some developers prefer to use positive state, such as `isValid`. In this case, setting
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
306 the disabled attribute to the model's isValid property would result in the button being disabled
977f674 @derickbailey docs for data-bind='enabled ...' and spec to prove data-bind='disable…
derickbailey authored
307 when the model is valid and enabled when the model is not valid. To correct this, a special case
308 has been added to enable and disable an element with `enabled`.
309
310 ````
311 <button id="someButton" data-bind="enabled isValid"></div>
312
313
314 someModel.set({isValid: false});
315 ````
316
317 This will disable the button when the model is invalid and enable the button when the model is
318 valid.
319
5f7e429 @srstrong Fixed readme to refer to the displayed data-bind attribute correctly
srstrong authored
320 #### displayed
8872555 @derickbailey bumped version to 0.3.3, docs and release notes
derickbailey authored
321
322 This allows you to specify that an element should be shown or hidden by setting the css
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
323 of the element according to the value of the model properties specified.
8872555 @derickbailey bumped version to 0.3.3, docs and release notes
derickbailey authored
324
325 ````
5f7e429 @srstrong Fixed readme to refer to the displayed data-bind attribute correctly
srstrong authored
326 <div data-bind="displayed isValid" />
8872555 @derickbailey bumped version to 0.3.3, docs and release notes
derickbailey authored
327
328 someModel.set({isValid: false});
329 ````
330
331 When the model's property is set to false, the HTML element's `display` css will be set
332 to `none`. When the model's property is set to true, the HTML element's `display` css
333 will be set to `block`.
334
335 #### hidden
336
5f7e429 @srstrong Fixed readme to refer to the displayed data-bind attribute correctly
srstrong authored
337 This is the inverse of `displayed`.
8872555 @derickbailey bumped version to 0.3.3, docs and release notes
derickbailey authored
338
339 ````
340 <div data-bind="hidden isValid" />
341
342 someModel.set({isValid: true});
343 ````
344
345 When the model's property is set to false, the HTML element's `display` css will be set
346 to `block`. When the model's property is set to true, the HTML element's `display` css
347 will be set to `none`.
348
8c02f6c @derickbailey added docs and release notes for data-bind substitutions
derickbailey authored
349 ### Data-Bind Substitutions
350
351 If a model's property is `unset`, the data-bind may not update correctly when using `text` or `html`
2c087d3 @derickbailey updated release notes for v0.3.7
derickbailey authored
352 as the bound attribute of the element.
8c02f6c @derickbailey added docs and release notes for data-bind substitutions
derickbailey authored
353
354 ````
355 <div data-bind="text something"></div>
356
357 model.set({something: "whatever"});
358 model.unset("something");
359 ````
360
361 The result will be a div with it's text set to "". this is handled through the data-bind's
362 substitutions for undefined values. The default substitution is to replace an undefined
2c087d3 @derickbailey updated release notes for v0.3.7
derickbailey authored
363 value with an empty string. However, this can be per attribute:
8c02f6c @derickbailey added docs and release notes for data-bind substitutions
derickbailey authored
364
365 ````
366 <div data-bind="text something"></div>
367 <div data-bind="html something"></div>
368
369 Backbone.ModelBinding.Configuration.dataBindSubst({
370 text: "undefined. setting text to this",
371 html: "&nbsp;"
372 });
373 model.set({something: "whatever"});
374 model.unset("something");
375 ````
376
377 The result of this example will be a div that displays "undefined. setting the text to this" and a
378 div whose contents is a single space, instead of being empty.
379
b2fef6d @derickbailey removed the formBinding code. it wasn't that useful and the configura…
derickbailey authored
380 ## Form Binding Conventions
bb8d234 @derickbailey documented data-bind
derickbailey authored
381
382 The following form input types are supported by the form convention binder:
57ed5b9 @derickbailey updated docs to list supported input types
derickbailey authored
383
384 * text
385 * textarea
47e4cbc @derickbailey updated the readme to talk about the configuration options for the co…
derickbailey authored
386 * password
57ed5b9 @derickbailey updated docs to list supported input types
derickbailey authored
387 * checkbox
e4417b1 @derickbailey updated documentation to discuss the behavior of select box convention
derickbailey authored
388 * select
389 * radio button groups
390
391 Radio buttons are group are assumed to be grouped by the `name` attribute of the
392 radio button items.
393
394 Select boxes will populate 2 separate fields into the model that they are bound to.
395 The standard `#fieldid` will be populated with the selected value. An additional
396 `{#fieldid}_text` will be populated with the text from the selected item. For example,
397 a selected option of
398
399 ````
400 <select id='company'>
401 <option value="foo_bar">Foo Bar Widgets, Inc.</option>
402 ...
403 </select>
404 ````
405
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
406 will populate the `company` property of the model with "foo_bar", and will populate
407 the `company_text` property of the model with "Foo Bar Widgets, Inc."
57ed5b9 @derickbailey updated docs to list supported input types
derickbailey authored
408
409 There is no support for hidden fields at the moment, because there is no 'change' event
410 that jQuery can listen to on a hidden field.
e4932c6 @derickbailey updated readme to talk about convention binding
derickbailey authored
411
47e4cbc @derickbailey updated the readme to talk about the configuration options for the co…
derickbailey authored
412 ### Configuring The Bound Attributes
7f2301e @derickbailey added basic support for htmlBindings - to go from the model's fields …
derickbailey authored
413
47e4cbc @derickbailey updated the readme to talk about the configuration options for the co…
derickbailey authored
414 The convention binding system allows you to specify the attribute to use for the convention, by
415 the input type. The default configuration is:
004fd10 @derickbailey updating readme with example and cautionary info
derickbailey authored
416
47e4cbc @derickbailey updated the readme to talk about the configuration options for the co…
derickbailey authored
417 ```
418 {
419 text: "id",
420 textarea: "id",
421 password: "id",
422 radio: "name",
423 checkbox: "id",
424 select: "id"
425 }
004fd10 @derickbailey updating readme with example and cautionary info
derickbailey authored
426 ````
427
47e4cbc @derickbailey updated the readme to talk about the configuration options for the co…
derickbailey authored
428 You can override this configuration and use any attribute you wish, by specifying any or all of
429 these input types when you call the model binding. This is useful when you have field ids that
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
430 do not match directly to the model properties.
b3f6e8e @derickbailey updated documentation to discuss setting all binding attributes
derickbailey authored
431
432 #### Override All Element Binding Attributes
433
434 The following will use use the `class` attribute's value as the binding for all input field:
435
436 ````
437 SomeView = Backbone.View.extend({
438 render: function(){
439 // ... some rendering here
2c8eb06 @derickbailey documentation for unbind method
derickbailey authored
440 Backbone.ModelBinding.bind(this, { all: "class" });
b3f6e8e @derickbailey updated documentation to discuss setting all binding attributes
derickbailey authored
441 }
442 });
443
444 <input type="text" id="the_model_name" class="name">
445 ````
446
447 If the same convention needs to be used throughout an application, and not just withing a single
448 view, the configuration can be set at a global level:
449
450 ````
1c09c20 @msaffitz Fixed typo in readme; configureAllBindingAttributes only takes attrib…
msaffitz authored
451 Backbone.ModelBinding.Configuration.configureAllBindingAttributes("class");
b3f6e8e @derickbailey updated documentation to discuss setting all binding attributes
derickbailey authored
452 ````
453
454 #### Override Individual Element Binding Attributes
455
456 The following will use a `modelAttr` attribute value as the convention for text boxes, only.
7f2301e @derickbailey added basic support for htmlBindings - to go from the model's fields …
derickbailey authored
457
458 ````
459 SomeView = Backbone.View.extend({
47e4cbc @derickbailey updated the readme to talk about the configuration options for the co…
derickbailey authored
460 render: function(){
461 // ... some rendering here
2c8eb06 @derickbailey documentation for unbind method
derickbailey authored
462 Backbone.ModelBinding.bind(this, { text: "modelAttr" });
7f2301e @derickbailey added basic support for htmlBindings - to go from the model's fields …
derickbailey authored
463 }
464 });
465
47e4cbc @derickbailey updated the readme to talk about the configuration options for the co…
derickbailey authored
466 <input type="text" id="the_model_name" modelAttr="name">
467 ````
468
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
469 When this text box has it's value changed, the model's `name` property will be populated with
47e4cbc @derickbailey updated the readme to talk about the configuration options for the co…
derickbailey authored
470 the value instead of `the_model_name`.
404d763 @derickbailey note about htmlBindings
derickbailey authored
471
1fe9132 @derickbailey updated readme to discuss global config
derickbailey authored
472 If the same convention needs to be used throughout an application, and not just withing a single
473 view, the configuration can be set at a global level:
474
475 ````
650e27a @derickbailey moved glocal attribute binding to the Configuration object
derickbailey authored
476 Backbone.ModelBinding.Configuration.configureBindingAttributes({text: "modelAttr"});
1fe9132 @derickbailey updated readme to discuss global config
derickbailey authored
477 ````
478
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
479 Now all text boxes will update the model property specified in the text box's `modelAttr`.
1fe9132 @derickbailey updated readme to discuss global config
derickbailey authored
480
bb8d234 @derickbailey documented data-bind
derickbailey authored
481 ## Pluggable Conventions
c3433dd @derickbailey spec to show that you can add your own conventions. documentation on …
derickbailey authored
482
483 The convention based bindings are pluggable. Each of the existing form input types can have it's
484 convention replaced and you can add your own conventions for input types not currently handled,
485 etc.
486
487 To replace a convention entirely, you need to supply a json document that has two pieces of
488 information: a jQuery selector string and an object with a `bind` method. Place the convention
489 in the `Backbone.ModelBinding.Conventions` and it will be picked up and executed. The `bind`
490 method receives three parameters: the jQuery selector you specified, the Backbone view, and
491 the model being bound.
492
4ea0020 @derickbailey updated the documentation for convention building
derickbailey authored
493 You can replace the handler of an existing convention. For example, this will set the
c3433dd @derickbailey spec to show that you can add your own conventions. documentation on …
derickbailey authored
494 value of a textbox called `#name` to some text, instead of doing any real binding.
495
496 ````
497 var nameSettingsHandler = {
498 bind: function(selector, view, model){
499 view.$("#name").val("a custom convention supplied this name");
500 }
501 };
502
503 Backbone.ModelBinding.Conventions.text.handler = nameSettingsHandler;
504 ````
505
4ea0020 @derickbailey updated the documentation for convention building
derickbailey authored
506 You can also create your own conventions that do just about anything you want. Here's an example
507 that modifies the contents of `<p>` tags:
508
509 ````
510 var PConvention = {
511 selector: "p",
512 handler: {
513 bind: function(selector, view, model){
514 view.$(selector).each(function(index){
515 var name = model.get("name");
516 $(this).html(name);
517 });
518 }
519 }
520 };
521
522 Backbone.ModelBinding.Conventions.paragraphs = PConvention;
523 ````
524
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
525 This example will find all `<p>` tags in the view and render the `name` property from the model
4ea0020 @derickbailey updated the documentation for convention building
derickbailey authored
526 into that paragraph, replacing all other text. Note that the name of the convention is set to
527 `paragraphs` when added to the conventions. This name did not exist prior to this assignment, so
528 the convention was added. If you assign a convention to an existing name, you will replace that
529 convention.
530
531 The list of existing conventions includes:
61d8847 @derickbailey updated release notes for v0.3.5
derickbailey authored
532
4ea0020 @derickbailey updated the documentation for convention building
derickbailey authored
533 * text
534 * password
535 * radio
536 * checkbox
537 * select
538 * textarea
bb8d234 @derickbailey documented data-bind
derickbailey authored
539 * formbinding
540 * databind
4ea0020 @derickbailey updated the documentation for convention building
derickbailey authored
541
c3433dd @derickbailey spec to show that you can add your own conventions. documentation on …
derickbailey authored
542 For fully functional, bi-directional binding convention examples, check out the source code
543 to Backbone.ModelBinding in the `backbone.modelbinding.js` file.
126af8d @derickbailey adding release notes, retroactive
derickbailey authored
544
545 ## Release Notes
546
6a05460 @derickbailey minified and updated readme
derickbailey authored
547 ### v0.4.0
548
549 * Major internal rewrite to facilitate maintenance, new features, etc
550 * No public API changes (at least, I hope not!)
551 * Now uses an internal object call `ModelBinder`, which is attached to the view that binding occurs on
552 * The `ModelBinder` instance stores all of the binding configuration and callbacks for that view, allowing much faster / easier / better unbinding
553
32963b0 @derickbailey bumped version to v0.3.10, minified, and updated readme
derickbailey authored
554 ### v0.3.10
555
556 * When binding to a select box and the model has a value not present in the box, reset the model's value to the box's
557 * Fix for using Backbone.noConflict(), Backbone was either wrong version or undefined when it was used inside ModelBinding.
558 * Added some missing ;
559 * Fix some documentation issues
560
e4b10a8 @derickbailey release notes for v0.3.9
derickbailey authored
561 ### v0.3.9
562
6a05460 @derickbailey minified and updated readme
derickbailey authored
563 * Fixed an issue with jQuery 1.6.4 determining if check boxes are checked or not
564 * Minor internal clean up
e4b10a8 @derickbailey release notes for v0.3.9
derickbailey authored
565
9fa80a5 @derickbailey bumped version to v0.3.8, with release notes and minified
derickbailey authored
566 ### v0.3.8
567
568 * Fix for Internet Explorer not having a `trim` method on strings
569
b5e4c0c @derickbailey updated readme and release note for v0.3.7's multiple data-bind
derickbailey authored
570 ### v0.3.7
571
572 * Data-bind multiple attributes for a single element
2c087d3 @derickbailey updated release notes for v0.3.7
derickbailey authored
573 * Default data-bind substitutaion to '' for all attributes
b5e4c0c @derickbailey updated readme and release note for v0.3.7's multiple data-bind
derickbailey authored
574
15d2337 @derickbailey release notes for v0.3.6
derickbailey authored
575 ### v0.3.6
576
577 * Fixed a bug that prevented `<input>` elements with no `type` attribute from being bound
578
61d8847 @derickbailey updated release notes for v0.3.5
derickbailey authored
579 ### v0.3.5
580
581 * Fixed a bug in configuring the binding attribute for textarea elements
582
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
583 ### v0.3.4
584
585 * Data-bind defaults to the html element's `text` if you only specify the model property: `data-bind="name"`
586 * Fixed issue with binding 1 / 0 to checkboxes (truthy / falsy values)
587
8872555 @derickbailey bumped version to 0.3.3, docs and release notes
derickbailey authored
588 ### v0.3.3
589
590 * Added data-bind attribute for setting an HTML element's `display` css
5f7e429 @srstrong Fixed readme to refer to the displayed data-bind attribute correctly
srstrong authored
591 * Added inserve of data-bind `displayed` as data-bind `hidden`
8872555 @derickbailey bumped version to 0.3.3, docs and release notes
derickbailey authored
592 * Corrected issue with binding a model's property to a checkbox, when the property is false
593
8c02f6c @derickbailey added docs and release notes for data-bind substitutions
derickbailey authored
594 ### v0.3.2
595
596 * Data-bind substitutions - lets you replace "undefined" with another, set value, when using data-bind
597
0d7b5d5 @derickbailey spec to fix data-bind issue with unsetting a model property
derickbailey authored
598 ### v0.3.1
599
1e051c1 @derickbailey defaulting the data-bind to update text of the html element if no att…
derickbailey authored
600 * Corrected issue with `unset`ing a model property, in the data-bind convention
0d7b5d5 @derickbailey spec to fix data-bind issue with unsetting a model property
derickbailey authored
601
63f3c92 @derickbailey release notes for v0.3.0
derickbailey authored
602 ### v0.3.0
603
0b009b6 @derickbailey updated release notes for v0.3.0
derickbailey authored
604 * **Breaking Change:** Changed the `Backbone.ModelBinding.call(view)` method signature to `Backbone.ModelBinding.bind(view)`
605 * Added ability to unbind model binding with `unbind` method, to prevent memory leaks and zombie forms
437566d @derickbailey added minified version to the repo
derickbailey authored
606 * Added backbone.modelbinding.min.js to the repository, compiled with
607 [Google's Closure Compiler Service](http://closure-compiler.appspot.com/home "Google's Closure Compiler Service")
0b009b6 @derickbailey updated release notes for v0.3.0
derickbailey authored
608 * Updated the selectors used for the conventions. Text inputs are now found with "input:text", which should
609 select all text inputs, even without a `type='text'` attribute (though this seems to be buggy in jQuery
610 v1.6.2)
611 * Significant internal restructuring of code
63f3c92 @derickbailey release notes for v0.3.0
derickbailey authored
612
e36b828 @derickbailey added release notes for v0.2.4
derickbailey authored
613 ### v0.2.4
614
6a05460 @derickbailey minified and updated readme
derickbailey authored
615 * Data-bind will bind the model's value immediately instead of waiting for the model's value to change
616 * Support `enabled` functionality for data-bind: `data-bind="enabled isValid"`
617 * Documented existing support for data-bind `disabled`: `data-bind="disabled invalid"`
e36b828 @derickbailey added release notes for v0.2.4
derickbailey authored
618
126af8d @derickbailey adding release notes, retroactive
derickbailey authored
619 ### v0.2.3
620
621 * Fixes for 'falsey' value bindings
622 * Update the docs to include when and where to call the model bindings
623
624 ### v0.2.2
625
626 * Making some global vars not global
627
628 ### v0.2.1
629
630 * Configuration to easily set all binding attributes for all elements
631 * Fix for IE
632 * Making some global vars not global
633
634 ### v0.1.0 - v0.2.0
635
636 * Added data-bind convention
637 * Added configuration options
638 * Conventions for all form input types
639 * Removed formBinding code
640 * Removed htmlBinding code
641 * Significant internal code cleanup and restructuring
c3433dd @derickbailey spec to show that you can add your own conventions. documentation on …
derickbailey authored
642
004fd10 @derickbailey updating readme with example and cautionary info
derickbailey authored
643 # Legal Mumbo Jumbo (MIT License)
376574a @derickbailey initial commit / structure
derickbailey authored
644
11a2e01 @derickbailey added copyright and license notice. cleaned up the way the code execu…
derickbailey authored
645 Copyright (c) 2011 Derick Bailey, Muted Solutions, LLC
376574a @derickbailey initial commit / structure
derickbailey authored
646
647 Permission is hereby granted, free of charge, to any person obtaining a copy
648 of this software and associated documentation files (the "Software"), to deal
649 in the Software without restriction, including without limitation the rights
650 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
651 copies of the Software, and to permit persons to whom the Software is
652 furnished to do so, subject to the following conditions:
653
654 The above copyright notice and this permission notice shall be included in
655 all copies or substantial portions of the Software.
656
657 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
658 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
659 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
660 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
661 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
662 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
663 THE SOFTWARE.
Something went wrong with that request. Please try again.