view README v1.0.2 changelog

README.md

@@ -139,7 +139,7 @@ model.set({
     'lastName': 'Brett-Bowen'
     });
 model.meta('name', ['firstName', 'lastName'], function(firstName, lastName) {
-    return lastName + ", " + Rhys;
+    return lastName + ", " + firstName;
 });
 model.get('name'); // returns "Brett-Bowen, Rhys"
 ```
@@ -222,6 +222,18 @@ wife.get('city') // returns New York
 
 if you want to listen to any change you can use bindAll and just pass in a function. and an optional handler.
 
+### autosaving ###
+
+you can tell a model to save itself when there are any changes or changes to particular attributes.
+
+To save the model on any change just call:
+
+myModel.autosave(opt_callback);
+
+or for certain attributes:
+
+myModel.autosave(['text', 'thumbnail'], opt_callback);
+
 ### unload ###
 
 there is also a bindUnload that takes in a function and an optional handler to be fired when the model's dispose() method is called.
@@ -582,6 +594,49 @@ goog.addSingletonGetter(myapp.Mediator);
 
 you can then register your object with the mediator and the messages that you may pass. This allows other modules that are listening for a specific message to run some initiation, or dispose when you unregister. You can listen to messages using the on method and stop using the off method. You can even test to see if anyone is listening for a message using the isListened method
 
+### registering an object ###
+
+you can let other objects know that you can fire specific messages. To do thisjust call the Mediator with the messages your object. To register an object just call:
+
+mvc.Mediator.register = function(object, messages)
+
+where object is the object you are registering and messages is an array of the messages it can fire (doing this will allow listeners to call their initialization functions if they match). Doing this will also decorate your object with a broadcast function so you can just call:
+
+myObj.broadcast(message, data)
+
+instead of calling it on the mediator. If you don't want this function added just pass along true as the third parameter to register.
+
+You can unregister an object (allowing listeners to call their dispose functions) by calling
+
+mvc.Mediator.unregister(obj, opt_messages)
+
+you can pass in an array of messages to only remove those messages or leave undefined to remove all
+
+### namespaces ###
+
+you can namespace your messages using '.' and then listen to messages using wildcards '*' for match anything and '%' to match anything within that level, so:
+
+a.* will match a.b.c
+a.%.c will match a.b.c but a.% won't
+
+You can change these wildcards by passing in when creating the mediator:
+
+mediator = new mvc.Mediator({
+  split: ':',
+  wild: '$',
+  wildlvl: '&'
+});
+
+The mediator will take wildcards in to account when testing for listened messages.
+
+### listening ###
+
+you can listen for messages by calling:
+
+mediator.on(message, fn, opt_handler)
+
+where message is the message (or array of messages) you're listening for, function is what is to be run and the opt_handler is what you want to bind the function to. The handler also has a dual purpose - if you register with a handler you can pass that object to mediator.off to remove all of the listeners with that handler. Otherwise the on function will return an id that can be passed to mediator.off to remove that listener.
+
 ## Testing ##
 
 To run tests you need to run plovr. From the root:
@@ -592,8 +647,94 @@ you can then run the tests by going to:
 
     http://localhost:9810
 
+## Experimental ##
+
+This is a section for functionality that has been added but has not had tests written for them or been developed fully. Use these at your own risk as they may change in future.
+
+### two way binding ###
+
+for your control you can setup two way binding like so:
+
+myControl.autobind(selector, template | options)
+
+The selector should work with the controls getEls function. Also it will not setup any setters if the selector is not a class name.
+
+A string can be given with attributes from the model to be populates surrounded by ${...}. for instance:
+
+myControl.autobind(goog.getCssName('-namefield', "{$lastname}, {$firstname}");
+
+or you can pass in an options object which should have the following signature:
+
+{
+  /* if the template is a string then the {$attr} found ill be added to the reqs
+  if it is a function then an object will be passed in with the signature:
+    {model: {
+        // these will be the values from reqs
+      },
+      // the data will be passed in as given in the options
+    }
+  this means if you are using soy templates you can get your attributes like so:
+    {$model['attr']}
+  they are passed in under the model namespace to allow for advanced compilation
+  */
+  template: string | function,
+  /*
+  an array of the attributes to be used from the model
+   */
+  reqs: Array,
+  data: {
+    /*
+      these will be passed in to the template function with the functions given being run with no arguments before placing in the value.
+     */
+    keys: string | Function
+  },
+  /* 
+  use this if you want to add a class when the first req is true, also clicking on the element will toggle the class
+  */
+  onClass: string,
+  /* this complements onClass and is shown if it is not on */
+  offClass: string,
+  noClick: boolean, // will turn off the onClass click binding
+}
+
+there is likely to be more options in future. The autobind will try to bind up input text & select elements (change on blur), elements based on class (onClass used) and checkitems (should use a boolean value from the model). These haven't all been tested and there may be more added. Other elements will only bind the result.
+
+### automatic collection listing ###
+
+will automatically display your elements and keep the display in order. just use this:
+
+myControl.autolist(mvc.Control, opt_el, opt_callback)
+
+the first argument should be a constructor function that inherits from mvc.Control that will be used to display the child model.
+
+the second argument is optional and will set the content element of the control, otherwise it will be put in the container element already given (usually the top element given by myControl.getElement() - though if you change the mvc.Control prototype chain is could be different, more on this in the next section).
+
+The third is a callback that will be passed the content element and is run after any changes to the displayed list.
+
+### custom mvc.Control prototype chain ###
+
+mvc.Control.create can be used to instantiate an mvc.Control with a different prototype chain. This can be useful if you want to use functions from another class in the goog.ui package that inherits from goog.ui.Component. You can create a new control like this:
+
+var myControl = mvc.Control.create(goog.ui.Control, app.MyControl, model, content);
+
+the first parameter is the base you want to use. In this case we're going to use goog.ui.Control instead of goog.ui.Component. The next parameter is our class that inherits from mvc.Control. you can leave this undefined if you wish to have just a generic mvc.Control. Then we add on the arguments we wish to pass, usually the first one will be the model, then anything else goog.ui.Control needs. Keep in mind that you want to pass along all the parameters so if you know you want app.MyControl to have goog.ui.Control in it's prototype chain then you'll need to pass in the content argument:
+
+app.MyControl = function(model, content) {
+  goog.base(this, model, content);
+};
+goog.inherits(app.MyControl, mvc.Control);
+
 ### changelog ###
 
+### v1.0.2 beta ###
+
+- autosave models
+- model can get and set multiple attributes
+- lots of mediator improvements
+- two way binding (experimental)
+- aut display of collection (experimental)
+- change mvc.Control prototype (experimental)
+
 ### v1.0.1 beta ###
 
 - more tests