spec to show that you can add your own conventions. documentation on …

…how to add / change conventions

readme.md

@@ -146,11 +146,53 @@ replaced by the value that is entered into the model's `a_field` field.
 *Note:* htmlBindings is experimental as I don't have an actual use for it right now. I put it in
 because it was easy and it might inspire some other ideas at some point.
 
-## Use At Your Own Risk
+### Pluggable Conventions
+
+The convention based bindings are pluggable. Each of the existing form input types can have it's
+convention replaced and you can add your own conventions for input types not currently handled,
+etc. 
+
+To replace a convention entirely, you need to supply a json document that has two pieces of
+information: a jQuery selector string and an object with a `bind` method. Place the convention
+in the `Backbone.ModelBinding.Conventions` and it will be picked up and executed. The `bind`
+method receives three parameters: the jQuery selector you specified, the Backbone view, and
+the model being bound.
+
+````
+var FooTextConvention = {
+  selector: "input\[type=text\]\[name=foo\]",
+  handler: {
+    bind: function(selector, view, model){
+      // bind the model and view, here.
+    }
+  }
+}
+
+Backbone.ModelBinding.Conventions.fooText = FooTextConvention;
+````
+
+You can also replace the handler of an existing convention. For example, this will set the
+value of a textbox called `#name` to some text, instead of doing any real binding.
+
+````
+var nameSettingsHandler = {
+  bind: function(selector, view, model){
+    view.$("#name").val("a custom convention supplied this name");
+  }
+};
+
+Backbone.ModelBinding.Conventions.text.handler = nameSettingsHandler;
+````
+
+For fully functional, bi-directional binding convention examples, check out the source code
+to Backbone.ModelBinding in the `backbone.modelbinding.js` file.
+
+## Early Stages Of Development
 
 backbone.modelbinding is still in the early stages and has limited functionality. Although 
 functionality is being built with unit tests, in a test-first manner, there is no
-guarantee that it will work the way you want it to or expect it to. Use at your own risk.
+guarantee that it will work. At all. Use at your own risk and be sure it works the way you
+expect before deploying to any production environment.
 
 # Legal Mumbo Jumbo (MIT License)
 

spec/javascripts/customConvention.spec.js

@@ -1,26 +1,53 @@
 describe("custom conventions", function(){
-  describe("replace the text input handler with a convention that sets the #name field value", function(){
-    beforeEach(function(){
-      this.model = new AModel({});
-      this.view = new AView({model: this.model});
-      this.oldHandler = Backbone.ModelBinding.Conventions.text.handler;
+  beforeEach(function(){
+    this.model = new AModel({});
+    this.view = new AView({model: this.model});
+    this.oldHandler = Backbone.ModelBinding.Conventions.text.handler;
+
+  });
+
+  afterEach(function(){
+    Backbone.ModelBinding.Conventions.text.handler = this.oldHandler;
+  });
 
+  describe("replace the text input handler", function(){
+    beforeEach(function(){
       var nameSettingsHandler = {
         bind: function(selector, view, model){
           view.$("#name").val("a custom convention supplied this name");
         }
       };
-      Backbone.ModelBinding.Conventions.text.handler = nameSettingsHandler;
 
+      Backbone.ModelBinding.Conventions.text.handler = nameSettingsHandler;
       this.view.render();
     });
 
-    afterEach(function(){
-      Backbone.ModelBinding.Conventions.text.handler = this.oldHandler;
-    });
-
     it("should set the custom field value when rendered", function(){
       expect(this.view.$("#name").val()).toBe("a custom convention supplied this name");
     });
   });
+
+  describe("add a brand new convention for paragraph tags", function(){
+    beforeEach(function(){
+      var PConvention = {
+        selector: "p",
+        handler: {
+          bind: function(selector, view, model){
+            view.$(selector).each(function(index){
+              var name = model.get("name");
+              $(this).html(name);
+            });
+          }
+        }
+      };
+
+      Backbone.ModelBinding.Conventions.paragraphs = PConvention;
+    });
+
+    it("should display the model name in the paragraph", function(){
+      this.model.set({name: "Gandalf Wizard"});
+      this.view.render();
+      expect(this.view.$("#aParagraph").html()).toBe("Gandalf Wizard");
+    });
+  });
 });

spec/javascripts/helpers/sample.backbone.app.js

@@ -24,6 +24,7 @@ AView = Backbone.View.extend({
       <input type='radio' id='graduated_maybe' name='graduated' value='maybe'>\
       <input type='checkbox' id='drivers_license' value='yes'>\
       <textarea id='bio'></textarea>\
+      <p id='aParagraph'></p>\
     ");
     this.$(this.el).append(html);
     Backbone.ModelBinding.call(this);