There are two ways to establish bindings and each has its place. The first is straight programatic binding via calling Bindable#bindNameToObjectWithKeyPath. The second method relies on the parameters dictionary passed to the constructor of a Bindable object.

Programatic Bindings

The programatic method of establishing bindings is probably the simplest to understand. Call bindNameToObjectWithKeyPath on a view or controller to establish a binding. You’ll need to provide values for the name of the binding you wish to create, the object you wish to which you want to bind, and the keypath on the object that will be bound.

For example:

var view= new coherent.View('node-id');
var obj= new coherent.KVO();

view.bindNameToObjectWithKeyPath('text', obj, 'title');

This works pretty much as you’d expect: The implementation of bindNameToObjectWithKeyPath observes the key path title on obj and calls the setText method on view whenever a change occurs. The view could update the title property of obj, but that’s a topic for another time.

There’s nothing wrong with creating bindings programatically, but I prefer to establish them when I create the view.

Declarative Bindings

The constructor of all Bindable objects accepts a dictionary containing additional parameters for the newly created object. Bindings are a special case of parameters, any keys that end in Binding are assumed to be a binding definition. So the previous example can be rewritten as:

var view= new coherent.View('node-id', {
                    textBinding: 'obj.title'
                });

But wait! There’s more! You can also specify options for the binding by changing the string key path into a dictionary¹:

var view= new coherent.View('node-id', {
                    textBinding: {
                        keypath: 'obj.title',
                        transformer: 'truncated',
                        nullValuePlaceholder: 'No Title',
                        noSelectionPlaceholder: 'No Image',
                        multipleValuesPlaceholder: 'Multiple Images'
                    }
                });

All entries in the dictionary are optional — except the keypath of course.

The placeholder entries provide values for the binding when the value of the key path represents a special marker value: null value (coherent.NullValueMarkerType), no selection (coherent.NoSelectionMarkerType), or multiple values (coherent.MultipleValuesMarkerType). These are typically only used when binding to the selection property of an ObjectController or ArrayController. The value of these entries may be of any type that will make sense to the view; no value need be provided if the default value specified by the view is acceptable.

The transformer entry is either the registered name of a ValueTransformer or an instance of a ValueTransformer. For example, if you’re not comfortable with the default truncating transformer, which truncates at 50 characters, you could create your own:

var view= new coherent.View('node-id', {
                    textBinding: {
                        keypath: 'obj.title',
                        transformer: new coherent.transformer.Truncate(20)
                    }
                });

Sometimes you need to transform model values somewhat ad hoc, like when converting a model value into a class name. In those cases, you can specify a transformation method directly in the binding definition:

var view= new coherent.View('node-id', {
                    textBinding: {
                        keypath: 'obj.title',
                        transformedValue: function(value)
                        {
                            if ('string'!==typeof(value))
                                return value;
                            return value.replace(/[^aeiou]+/gi, '');
                        }
                    }
                });

All About Context

There’s one important thing missing in the code samples from the previous section: the object value for bindNameToObjectWithKeyPath. The declarative method takes the value of object from the currently active context. There is always an active context. In many cases, it’s the global context, but there are also contexts for NIBs and the internal structure of views.

First, let’s make the example work with the global context:

var obj= new coherent.KVO();
coherent.registerModelWithName(obj, 'obj');

var view= new coherent.View('node-id', {
                    textBinding: 'obj.title'
                });

The call to registerModelWithName wires up an object to the global context with a given name. Behind the scenes this is nothing more than a call to setValueForKey(obj, 'obj') on the global context.

NIB Context

The global context isn’t usually where bindings will be evaluated, however. Most bindings get evaluated in the context of a NIB. A NIB represents a collection of views and controllers for a specific chunk of your application. Each entry in the NIB is exposed in the active context.

In the following example, the NIB context will contain entries for gallery, data, and controller:

NIB({

    'gallery': VIEW(NIB.asset('gallery.html'), {
                    ':root': coherent.View({
                                visibleBinding: 'controller.arrangedObjects.@count'
                            }),
                    'img': coherent.Image({
                                srcBinding: 'controller.selection.href'
                            }),
                    'p': coherent.View({
                                textBinding: 'controller.selection.caption'
                            }),
                    'a.next': coherent.Anchor({
                                enabledBinding: 'controller.canSelectNext',
                                target: 'controller',
                                action: 'selectNext'
                            }),
                    'a.prev': coherent.Anchor({
                                enabledBinding: 'controller.canSelectPrevious',
                                target: 'controller',
                                action: 'selectPrevious'
                            })
                }),

    'data': NIB.asset('gallery.json'),

    'controller': coherent.ArrayController({
                    contentBinding: 'data.photos'
                }),

    'owner': {
        view: 'gallery'
    }

});

In addition to the entries defined in the NIB, there are a number of special entries that represent objects external to the context: owner and application. The owner entry is usually an instance of coherent.ViewController and application is the shared coherent.Application instance. You can connect views and data objects to the owner or application by specifying the linkages in a dictionary associated with those keys.

View Context

In addition to NIB contexts, if you create subclasses of coherent.View, you’ll probably encounter View contexts. During initialisation of a view and its children, the context is set to the containing view. This allows child views to access properties of their parent.

For example:

views.MyView= Class.create(coherent.View, {

    title: coherent.View({
                textBinding: 'representedObject.title'
            })

});

Then later, you can do the following:

var view= new views.MyView('my-view-id');
var obj= new coherent.KVO();
view.setValueForKey(obj, 'representedObject');

Template Context

The final context you’re likely to encounter is the template context created for each item in coherent.CollectionView#newItemForRepresentedObject. This is something of a special case, because unlike the other contexts, the template context contains all the entries from the context used to create the CollectionView plus an entry (representedObject) for the current item in the collection.

Here are the performance metrics for Coherent 2.0 running on IE 8 (in a VM):

      direct:  5.688s for 50 iterations  (Avg: 113.755ms)
     derived:  6.086s for 50 iterations  (Avg: 121.720ms)
     methods:  9.793s for 50 iterations  (Avg: 195.860ms)
      notify: 10.946s for 50 iterations  (Avg: 218.910ms)
notify class:  6.785s for 500 iterations (Avg:  13.570ms)

Coherent’s never been a stellar performer in Internet Explorer. That’s something of an understatement, but I’ve always felt the blame rested largely on IE’s craptacular Javascript engine.

Now, I’m not so sure.

Below are the same run times for the same performance tests, but this time the tests are running against the new optimised code in Coherent 3.0:

      direct:  4.309s for 50 iterations  (Avg:  86.170ms)
     derived:  0.625s for 50 iterations  (Avg:  12.500ms)
     methods:  0.910s for 50 iterations  (Avg:  18.205ms)
      notify:  8.356s for 50 iterations  (Avg: 167.110ms)
notify class:  4.547s for 500 iterations (Avg:   9.094ms)

Clearly, I’m doing something right. All the unit tests still pass. And I’m getting a 9.7× speed improvement for derived property access — that’s when accessing properties of a class derived from coherent.KVO, a 10.7× speed improvement for calling getter and setter methods, and significant 1.3× to 1.5× improvement for the other operations.

The same code running in other browsers (Safari 4.0, WebKit nightly, Firefox 3.5 and Firefox 3.6) all see speed improvements between 1.3× and 2.0×, but nothing nearly as dramatic as IE.

Below are the performance numbers from WebKit nightly running Coherent 2.0:

      direct: 304.750ms for 100 iterations  (Avg: 3.047ms)
     derived: 324.750ms for 100 iterations  (Avg: 3.248ms)
     methods: 286.250ms for 100 iterations  (Avg: 2.862ms)
      notify: 742.750ms for 100 iterations  (Avg: 7.428ms)
notify class: 257.750ms for 1000 iterations (Avg: 0.258ms)

And WebKit nightly running Coherent 3.0:

      direct: 195.500ms for 100 iterations  (Avg: 1.955ms)
     derived: 204.000ms for 100 iterations  (Avg: 2.040ms)
     methods: 213.500ms for 100 iterations  (Avg: 2.135ms)
      notify: 468.750ms for 100 iterations  (Avg: 4.688ms)
notify class: 162.500ms for 1000 iterations (Avg: 0.163ms)

This is just the result of changes to the core methods of coherent.KVO and coherent.KeyInfo. Of course, there’s still more performance tuning to come. But I don’t think I’ll have anything this dramatic to report again…

The biggest problem is that a lot of it is simply not accurate any more. However, I’m going to leave it there for historical interest — I’m a bit surprised reading about my first efforts back in 2005. Maybe it will interest other developers too.

Probably the most important feature of the new site is the API documentation. This is greatly expanded from the original documentation from Coherent 1.0. And it will only get better as I continue to review the code and add doc comments.

Essentially, I’m thinking of something like the following:

sample.MyWidget= Class.create(coherent.Widget, {

    init: function()
    {},

    title: TextWidget('div.header em', {

                htmlKeyPath: '*.selection.title',

                onclick: function(event)
                {
                    ... handle clicking on the title ...
                },

                ... etc ...

            }),

    nextButton: Widget('div.controls button.next', {

                    onclick: function(event)
                    {
                        ... go to the next image ...
                    }

                }),

    ... etc ...
});

Just before calling init, the Widget framework should create sub-widgets for title and nextButton. For the title, its html binding would be connected to the key path selection.title from the outer widget. Additionally, a click handler would be created with the given method. The scope of the onclick method for title would be MyWidget rather than the actual TextWidget.

Using the new Selector library, you could create widgets based on any CSS query rather than just a direct descendant or ID. I don’t think there’s any need to have sub-widgets within the sub-widgets. If that’s what you’re looking for, you probably want to look at creating a widget rather than declaring the structure.

To be backward compatible, the node specifier (div.header em) should be checked to see whether it is an ID. This means that #foo would be equivalent to simply foo. Because presently, Coherent allows you to specify the ID of the node as a string without the preceding hash. Perhaps I can generate a deprecation warning…

Bindings and event handlers on sub-widgets

The second parameter to the widget declarations is how you may specify bindings for the sub-widget as well as events to handle. This hash should contain either key path entries (e.g. htmlKeyPath) or event handler entries (e.g. onclick). Essentially, after finding the node via a selector query, Coherent will enumerate the keys in this hash and for keys with a string value, call setAttribute on the node with the key and value. For keys with a function value, Coherent will observe the event of the same name as the key after stripping the on prefix (e.g. onclick ⇒ click).

This is roughly similar to how the setupNodeWithSelectors method works. So this seems like a reasonable approach.

Changes to Coherent’s OOP model

In order to make this work, I’d need to tweak Coherent’s OOP model a bit. Essentially, JavaScript assigns special meaning to using a function as the target of the new operator. What I’d be doing it taking advantage of this to branch and execute different code depending on how the constructor was invoked.

Instead of allowing the constructor to perform this double duty, what if Coherent shunted off non-constructor invocations of the constructor to a factory method? This factory method would be expected to return another function which could be invoked to create an instance of the class.

So consider the following class definition:

sample.MyClass = Class.create({

    constructor: function(arg1, arg2)
    {
        this.prop1= arg1;
        this.prop2= arg2;
    },

    __factory__: function(arg2)
    {
        var klass= this;

        return function(arg1)
        {
            return new klass(arg1, arg2);
        }
    },

    // ... etc ...
});

Because the factory method would be inherited by sub-classes, there will have to be some slight magic under the covers. Basically, Coherent will invoke the factory method in the scope of the class itself, therefore this will be equal to the class on which the factory method was invoked rather than the class on which the factory method was defined.

This allows you to write code like the following:

var foo= sample.MyClass('abc');
// ... later ...
var bar= foo('def');

If a class doesn’t define a __factory__ member, I think Coherent should simply throw an Error. After all, you almost never get what you’re expecting in that case.

There’s no getting around the fact that writing a __factory__ method will be something of a pain. But for the primary use of creating declarative sub-widgets, there need only be one factory on the base Widget class. All sub-classes of Widget will be able to use the default factory method, unless the sub-class has defined its own constructor with additional/different arguments.

Now all I need to do is code it…

Lots of folks have come out of the woodwork to either say they’ve been looking for something like this for ages. I guess there are more fans of the Apple development model than I thought. And obviously a lot of us build Web applications either for a living or in our spare time.

As I’ve been working on some features I’ve planned for 1.1, I’ve run across some strange problems with selectors which seems to tie into John Resig’s recent blog post about selectors.

I see nothing wrong with the following mark up:

<div id="outer">
    <ul contentKeyPath="links.arrangedContent">
        <li><img srcKeyPath="*.iconHref" width="16" height="16">
            <em textKeyPath="*.title">The Title</em>
        </li>
    </ul>
</div>

The offensive parts to the purists are contentKeyPath, srcKeyPath, and textKeyPath. Now browsers have always been very forgiving when it comes to extra attributes on nodes, but the purists think it’s sinful (or something) to take an expedient approach to adding useful information to the mark up.

I understand — really, I do — the whole separation of presentation from content and content from behaviour. However, in this particular case, I’m not actually marking up the content. I’m marking up the template for the content. To me, it makes a difference. But I understand I’ll never convince you if you’re already against custom attributes.

An alternative to custom attributes

So the other day I was kicking around an idea for an alternative syntax for describing the bindings between elements and the data model. Ideally I could have a format similar to the following:

ul: {
    contentKeyPath: links.arrangedContent
},

ul li img: {
     srcKeyPath: *.iconHref
},

ul li em: {
    textKeyPath: *.title
}

Gosh, that looks just like JSON… so how about this:

{
    'ul': {
        contentKeyPath: 'links.arrangedContent'
    },

    'ul li img': {
         srcKeyPath: '*.iconHref'
    },

    'ul li em': {
        textKeyPath: '*.title'
    }
}

Now all we need is a selector engine to hook this up to the nodes. It would be ideal if every browser supported querySelectorAll, but so far only Safari seems to have an implementation of querySelectorAll¹ and FireFox 3 won’t include it, which boggles the mind a bit. Fortunately, Diego Perini has written an excellent selector engine called NWMatcher and has graciously permitted me to include it in Coherent. This gives me coverage for the vast majority of browsers that don’t support querySelectorAll. And Diego’s code is pretty fast too.

So now I’m thinking in terms of what the right API should be for this. I’m thinking something like the following:

coherent.setupNodeWithSelectors($('outer'), {
    'ul': {
        contentKeyPath: 'links.arrangedContent'
    },

    'ul li img': {
         srcKeyPath: '*.iconHref'
    },

    'ul li em': {
        textKeyPath: '*.title'
    }
});

But imagine my surprise when I read about the wacky behaviour of querySelectorAll this morning. This potentially explains some bugs I experienced the first time I tried to implement the selector API. I’m not entirely certain where I come down on the issue. But it sure seems that if you’re going to add a native feature to provide similar functionality to the numerous selector engines available, you should probably define the spec as closely as possible to the majority behaviour.

Mimicking “standard” behaviour

I think my best bet is to mimic the standard behaviour of the prevailing libraries. My initial solution is to prefix the selector with the ID of the scope node. So in the call above, the selectors translate as follows:

Fortunately, both Safari’s implementation of querySelectorAll and Diego’s code allow the first part of the selector to match the node itself. This solves my problem until the W3C api guys decide to change the API. Then I’ll need to provide one behaviour for Safari 3.1 and another for future versions.

Joy.

On the other hand, this means that PartList will support selectors rather than the pseudo-selectors available in 1.0. I won’t say there have been numerous occasions where I’ve wished for this feature, but that’s only because I always had the option of tacking on a class to the target nodes. Now I won’t have to.

If you’ve downloaded either the ZIP file or pulled down the SVN repository, you should probably update to get the latest bug fixes and other goodies.

Properties

In object oriented programming, a property is any attribute of an object. Technically properties might be public or private, but principally, I usually think of properties as publicly accessible values. Any bit of code may query the value of a property or set its value.

Most modern object-oriented programming languages have some concept of properties. Some older languages like Java and C++ fake it via getter and setter methods. But some languages like Python, Ruby, and C# have native properties. JavaScript in Class A browsers¹ also supports properties using the following syntax:

var someObject= {

    get foo()
    {
        return this.theValueOfFoo;
    },

    set foo(newFoo)
    {
        this.theValueOfFoo= newFoo;
    }

};

It’s not the ideal syntax, but it’s quite a bit better than the alternative:

var someObject= {};
someObject.__defineGetter__('foo', function() {
    return this.theValueOfFoo;
});
someObject.__defineSetter__('foo', function(newFoo) {
    this.theValueOfFoo=newFoo;
});

You can then access this property directly and under the covers, JavaScript will call the correct methods.

someObject.foo="I am Foo!";
window.alert(someObject.foo);

That’s all great so long as none of your visitors uses Internet Explorer. The barnacle encrusted JavaScript engine employed by Internet Explorer saw its last significant feature improvement nearly a decade ago. So it doesn’t have any of the shiny new features found in Class A browsers. It’s the killjoy of the browser community.

So unless you’re certain all your visitors have modern browsers, you’re stuck writing getter and setter methods like in Java or C++². So the example above becomes:

var someObject= {

    getFoo: function()
    {
        return this.theValueOfFoo;
    },

    setFoo: function(newFoo)
    {
        this.theValueOfFoo= newFoo;
    }

};

This may not seem like a big difference, but you’ll notice it when you go to use someObject:

someObject.setFoo('I am Foo!');
window.alert(someObject.getFoo());

This may feel natural if you’re a C++ or Java programmer, but then you’re also probably accustomed to chewing broken glass, sticking needles in your eyes, and other painful party tricks.³

Observing properties

One feature built into Coherent is the ability to observe the changes made to an object’s properties. For any KVO-compliant⁴ object, you may add an observer via a call to:

someObject.addObserverForKeyPath(observerObj, observerObj.observeFooChange,
                                 "foo");

Whenever the foo property of someObject changes, the observeFooChange method of observerObj will be called with the previous and new value. Exactly what observerObj chooses to do with the change information is up to you the developer.

For properties you implement via getter and setter methods, there’s nothing you need to do to notify observers that the property has changed. However, if your property is just a regular value on your object, you’ll need to use one of two methods to notify observers that the value has changed.

The first technique is to wrap modification of the property with calls to willChangeValueForKey and didChangeValueForKey. So to keep with the previous observer example, lets look at some code in someObject that updates the foo property:

    addOneToFoo: function()
    {
        this.willChangeValueForKey('foo');
        ++this.foo;
        this.didChangeValueForKey('foo');
    },

This technique allows you to make numerous modifications to the foo property and only signal the observers when you’re good and ready. Additionally, you can use willChange/didChange to wrap calls to a number of methods which all trigger changes to the same property. These changes will be delayed and coalesced into a single update.

The second technique is to modify your properties by calling setValueForKey or setValueForKeyPath. This is a pseudo-atomic operation that updates the property value and notifies observers all at once. Of course, under the covers, setValueForKey calls willChange and didChange for you. The addOneToFoo method could then be written as:

    addOneToFoo: function()
    {
        this.setValueForKey(this.foo+1, 'foo');
    },

Not substantially different, but if you call setValueForKey more than once, you (might) get more than one change notification.

Coalesced property changes

One of the important responsibilities of the willChangeValueForKey and didChangeValueForKey pair is to coalesce property changes. If you plan to call multiple methods that might trigger changes for a particular property, you can wrap those calls with a willChange/didChange pair. The change notification will only be triggered when the final didChangeValueForKey method is called.

Additionally, the first time willChangeValueForKey is called, it will retrieve the current value of the property. When the final didChangeValueForKey method is called, the change notification will only be triggered when the previous value and new value are different. This is important to keep the number of change notifications down to a manageable level.

Property change coalescing occurs no matter how you update your properties. So whether you call setValueForKey, willChangeValueForKey/didChangeValueForKey, or write your own getter/setter methods (e.g. getFoo and setFoo), if the new value isn’t any different than the existing value, no change notification will occur.

Bindings

At their most simple, bindings are a two way method of keeping objects synchronised without having to write an enormous amount of glue code. Through a binding, you are creating a mediated connection between a view or controller and your data model. Changes to one are reflected in the other automatically.

This can be reflected in your UI with the following mark up:

<div class="inline-demo">
<fieldset id="properties-bindings-demo1">
    <label>Name:</label>
    <div><input type="text" valueKeyPath="person.name"
                nullPlaceholder="Your Name"></div>
    <label>Greeting:</label>
    <div>Hello, <span textKeyPath="person.name"
                      nullPlaceholder="Your Name"></span>.</div>
</fieldset>
</div>

<script>
    coherent.DataModel('person', {name: 'Bozo the Clown'});
    coherent.setupNode($('properties-bindings-demo1'));
</script>

And ultimately, this yields the following interaction:

As you modify the value in the input field, the values are pushed into your data model. First the InputWidget calls setValueForKeyPath to update the data model with the current value of the input field. The Person object triggers a change notification, which is observed by the TextWidget. The TextWidget updates its associated DOM node with the new value.

Bindings can be properties too

It isn’t necessary to expose your bindings as properties, but it can be useful. For example, the InputWidget exposes a value binding, however, the value binding isn’t also exposed as a property: you can’t call setValue and getValue to retrieve the current widget value. On the other hand, the ObjectController exposes the editable binding and also has an editable property.

Typically, when a property is also exposed as a binding, setting the property should immediately set the binding. So, in the case of the ObjectController, setting the value of the editable property will automatically update the object at the other end of its editable binding.

Wrapping it up

An understanding of properties and bindings is essential to making effective use of Coherent. With luck, this overview has shed light on some of the essential details and given you confidence to dive in and write some code. It won’t hurt. I promise.

It’s UI code

Fundamentally, the purpose of Coherent is to make writing the UI of Web applications more like writing the UI of desktop applications. And when you really think about the top needs for UI code, blinding speed just isn’t one of them.

For high-level code, I’d much rather trade off a little bit of speed in favour of a more flexible, de-coupled implementation. For low-level code, like CSS Selector engines, you absolutely must have the fastest you can get. Until your browser supports the W3C Selectors API, like nightly WebKit builds, you want your JavaScript implementation to be as fast as possible. But for high-level APIs intended to speed application development, a few extra cycles lost here and there won’t hurt.

Trade-offs

One of the trade-offs that I’m making revolves around when to perform the method wrapping. If this were desktop software, the model objects might live a life partially independent of the UI. It’s conceivable your code might perform some sort of background processing and fill in your model objects. In that case, you don’t necessarily want to be calling wrapped methods, you want every last drop of processor power at your disposal. In that case, you’d only want to wrap methods when the object becomes the target of an observer.

But for Web applications, the presumption I’m making is that the data wouldn’t be on the client in the first place if it weren’t taking part in the UI. Therefore, let’s spend the minimum amount of time creating wrapped methods (they don’t grow on trees, you know) and most likely, once a property gets observed, the rest of the instances of that class are also likely to get observed as well.

So the trade off in this case is less time spent wrapping methods in exchange for a few more change notifications sent when no one cares.

Writing the code for you

It’s been suggested that Coherent could use a facility to automatically generate getter and setter methods. The syntax I’m thinking would be something like the following:

var MyClass= Class.create(coherent.Bindable, {

    exposedBindings: ['content'],

    properties: ['name', 'description'],

    ...

});

If you leave out any implementation of the content binding Coherent would automatically generate the following:

    ...

    observeContentChange: function(change, keyPath, context)
    {
        this.setContent(change.newValue);
    },

    setContent: function(newContent)
    {
        this.__content= newContent;
    },

    getContent: function()
    {
        return this.__content||null;
    },

    ...

And if you didn’t implement methods for the name and description properties, Coherent would generate the following methods to implement them:

    ...

    setName: function(newName)
    {
        this.__name= newName;
    },

    getName: function()
    {
        return this.__name||null;
    },

    setDescription: function(newDescription)
    {
        this.__description= newDescription;
    },

    getDescription: function()
    {
        return this.__description||null;
    },

    ...

I’m not certain how valuable this really is. Is it that much better than calling this.setValueForKey("Bob", "name") when you need to set the object’s name? It would be a bit more clear, and I could generate the wrapped versions at the same time to reduce one layer of indirection.

There might be additional benefits to knowing in advance the list of properties a class exposes, but I don’t know whether limiting you to only the properties you declare is right in such a dynamic language as JavaScript. Still, it’s something to think about post 1.0.

Oh, and if you haven’t tried Pandora yet, what the heck are you waiting for? This is one of the coolest things I’ve run across in ages. Of course, now my wallet is going to be completely empty because I’ve been turned onto a half dozen musicians I’d never heard of before…