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…

For this tutorial, we’re going to build a simple photo gallery to display a static list of images with captions. In a future tutorial, we’ll see how we can expand this sample to pull image information from Flickr or other sources.

Caption

Next Previous

The buttons at the bottom allow visitors to cycle forward and backwards through the list of available photos. In this case, wrapping around is not supported, but would be easy to implement.

Go ahead, try it. It just works.

Parts is parts

Obviously, our widget is nothing without some HTML to hook it up to. Let’s create the bare minimum of markup: we need an image to display the current photo, a paragraph to present the photo’s caption, and two links to serve as our next and previous button. We’ll rely on Safari’s top-notch CSS support to make it all look pretty.

<div id="photo-gallery">
    <img src="photos/molly-1.jpg">
    <p>Caption</p>
    <a href="#" class="next">Next</a>
    <a href="#" class="prev">Previous</a>
</div>

That’s simple. Our markup maps to our widget through Parts (and PartLists not seen here). A Part is a lightweight stand in for a DOM node (often called a flyweight). All a Part contains is the ID of the DOM node, and if the node doesn’t have one, it will be assigned one. This alleviates a lot of headaches for the server side of things, because you don’t have to write code to generate unique IDs. In addition, because you won’t have DOM node references in your local variables, you reduce the risk of memory leaks in Internet Explorer when creating closures. To retrieve the DOM node, you simply invoke the Part as if it were a function (which it is) and if the node exists, you’ll get back a reference to it.

The real work happens in our widget’s init method. After initialising its images and selectedIndex properties to reasonable default values, the widget creates two widgets of its own. The first is an image widget and the second is a text widget. The first parameter to each constructor is the node that will be managed by the widget. The second and third parameters are the relative data source for the widget and a map describing where the widget can find its data; we’ll get to this in the section on Data Binding.

We also add listeners for the click event on both the next and previous buttons. At the moment, Coherent depends on some methods having an API similar to the Prototype library, but expect this dependency to go away in the future.

var PhotoGallery= Class.create(coherent.Widget, {

    ...

    init: function()
    {
        this.images= null;
        this.selectedIndex= -1;

        new coherent.ImageWidget(this.image(), this, {
                                    src: '*.selectedImage.href'
                                 });
        new coherent.TextWidget(this.caption(), this, {
                                    text: '*.selectedImage.caption'
                                });

        Event.observe(this.nextButton(), 'click',
                      this.nextButtonClicked.bindAsEventListener(this));
        Event.observe(this.prevButton(), 'click',
                      this.prevButtonClicked.bindAsEventListener(this));
    },

    image: Part('img'),
    caption: Part('p'),
    nextButton: Part('a.next'),
    prevButton: Part('a.prev'),

    ...

});

For widgets like our photo gallery, it really is this simple. As your widgets get more complex, of course, your init logic will get a bit more complex. But by using sub-widgets, Parts and PartLists, your work can be less onerous.

Handling events

At the moment, our photo gallery isn’t very interesting, but before we get into stuff that’s specific to the Coherent library, let’s implement the click event handlers to allow the visitor to switch between the available images.

The logic for both nextButtonClicked and prevButtonClicked is basically the same: stop the DOM event from invoking the anchor, return if there are no images or if we’re at the beginning or end of the list (for previous and next respectively), otherwise, update the selectedIndex property to reflect either the previous or next index. And finally, update the navigation controls.

Updating the navigation controls is similarly very simple: if we’re at the beginning of the list, add the disabled class to the previous link, otherwise remove it; and if we’re at the end of the list, add the disabled class to the next link, otherwise remove it. If there are no images at all, disable both buttons.

var PhotoGallery= Class.create(coherent.Widget, {
    ...

    nextButtonClicked: function(event)
    {
        Event.stop(event);
        if (!this.images)
            return;

        var newIndex= this.selectedIndex+1;
        if (newIndex>=this.images.length)
            return;

        this.setValueForKey(newIndex, 'selectedIndex');
        this.updateNavigation();
    },

    prevButtonClicked: function(event)
    {
        Event.stop(event);
        if (!this.images)
            return;

        var newIndex= this.selectedIndex-1;
        if (newIndex<0)
            return;

        this.setValueForKey(newIndex, 'selectedIndex');
        this.updateNavigation();
    }

    updateNavigation: function()
    {
        if (!this.images || !this.selectedIndex)
            Element.addClassName(this.prevButton(), 'disabled');
        else
            Element.removeClassName(this.prevButton(), 'disabled');

        if (!this.images || this.selectedIndex+1>=this.images.length)
            Element.addClassName(this.nextButton(), 'disabled');
        else
            Element.removeClassName(this.nextButton(), 'disabled');
    },

    ...
});

That’s it. Again, this is a pretty simple widget, but you’ll find that using Parts and sub-widgets makes your event handlers considerably simpler.

Widget Properties

In the previous code fragment, you may have noticed two calls to an unfamiliar method: setValueForKey. This method is declared on the coherent.KVO class which is an ancestor of coherent.Widget. Essentially, calling setValueForKey(newValue, keyName) is equivalent to the following code:

this.willChangeValueForKey(keyName);
this[keyName]= newValue;
this.didChangeValueForKey(keyName);

Of course, that clears things up, doesn’t it? The call to willChangeValueForKey lets observers know that you intend to change the value of a particular property. After you change it, calling didChangeValueForKey alerts observers that the value has actually changed. Under the covers, didChangeValueForKey will check to make certain that the value actually has changed before invoking the observers’ change notification handlers. Calling setValueForKey does this for you.

Now you might be wondering whether you need to add calls to willChangeValueForKey and didChangeValueForKey to all your setter methods. Good news! The answer is no. Coherent will automatically wrap your setter with calls to willChange… and didChange… so you don’t need to worry about it.¹

In addition to the list of images and the index of the selected image, our photo gallery widget needs a property to reflect the selected image itself. We’ll define an accessor method, because its value is computed rather than set.² The method checks first to make certain the images property has a value and that an image is actually selected, returning null if either condition is false. Otherwise, it returns the object in the images array at the index determined by selectedIndex.

Next we need to determine how the properties interact. In this case, the selectedImage property is dependent on the value of selectedIndex and images. So we declare this dependency relationship in keyDependencies — a special property you can add to your class definition and is processed via the __subclassCreated method of the Widget class. Each entry in the keyDependencies map is the name of a property and its value is an array of other properties upon which the property value depends.

var PhotoGallery= Class.create(coherent.Widget, {
    ...

    getSelectedImage: function()
    {
        if (!this.images || -1===this.selectedIndex)
            return null;
        return this.images[this.selectedIndex];
    },

    keyDependencies: {
        'selectedImage': ['selectedIndex', 'images']
    },

    ...
});

Normally, widgets will have considerably more properties than our photo gallery, but each property will be implemented roughly like selectedImage.

Data Binding

Most widgets need to interact with the data from your application. (If not, what the heck do they do?) Widgets need to declare these data connection points, called bindings, so that Coherent can manage notifying the widget when a bound value changes. Widgets can also push changes out to the bound data as well, and Coherent will notify the owner of the data via a change notification.

There are two places that Widgets can look to resolve their bindings: in the global data model and in their relative data source (parameter #2 to the constructor). In the init method, we encountered two bindings: the src for the ImageWidget and the text for the TextWidget. The third argument to the constructors specifies a map in which the keys are the names of the widget’s exposed bindings and the values are paths to where the widgets should look for their data. Paths that begin with * are assumed to be relative to the data source provided as parameter #2 to the constructor. Other paths are to objects that live in the global data model, which we’ll explore in a future tutorial.

For our photo gallery, the first step is to define the external data our widget is expecting. In order for our widget to respond to changes to the external data, we must define observer methods for each exposed binding. Coherent will automatically call our widget’s observer method when external data changes.

We’ll expose bindings for the list of images and the index of the selected image. Because this is such a simple example, when these values change in the data model, we’ll just update a local property with the new value.

var PhotoGallery= Class.create(coherent.Widget, {
    ...

    exposedBindings: ['images', 'selectedIndex'],

    observeImagesChange: function(change, keyPath, context)
    {
        if (coherent.ChangeType.setting!==change.changeType)
            return;

        this.setValueForKey(change.newValue, 'images');
        this.updateNavigation();
    },

    observeSelectedIndexChange: function(change, keyPath, context)
    {
        this.setValueForKey(change.newValue, 'selectedIndex');
        this.updateNavigation();
    },

    ...
});

Through the magic occurring behind the scenes, these two observer methods will cause a change notification for the photo gallery’s selectedImage property, which in turn will generate change notifications for the src and text bindings of the image widget and text widget. Your UI will update automatically.

In most cases, your observer methods will not usually be this simple. However, you can often factor out some logic like the call to the method updateNavigation — which enables and disables the next and previous buttons.

Create the Widget

The data for our photo gallery could come from any where, but for now, we’ll just hard-code some photos and captions into our HTML document. Our galleryData structure contains an entry for the index of the selected photo as well as an array of photos. These don’t have to both be in the same place, in fact, a future tutorial will demonstrate using an ArrayController to manage the selection and an AjaxController to fetch the photos from Flickr.

var galleryData= {
    selected: 0,
    photos: [
        {
            caption: "Molly on the slide.",
            href: "photos/molly-1.jpg"
        },
        {
            caption: "Monkey in training",
            href: "photos/molly-2.jpg"
        },
        {
            caption: "Spaz attack!",
            href: "photos/molly-3.jpg"
        },
        {
            caption: "Ride `Em, Molly!",
            href: "photos/molly-4.jpg"
        },
        {
            caption: "Don't mess with my zebra.",
            href: "photos/molly-5.jpg"
        }
    ]
};

Now that we have data, we can create our widget. All that’s needed is to instantiate a PhotoGallery object. Just like when we created the ImageWidget and TextWidget, we pass the DOM node for the widget (as an ID this time), the object that will be the source of the widget’s data, and a map indicating how the exposed bindings hook up to the data source.

new PhotoGallery('photo-gallery', galleryData, {
                    images: '*.photos',
                    selectedIndex: '*.selected'
                 });

See it in action

If this sounds simple, it really is. In case you didn’t notice, the photo gallery at the top of the page was live. And if you’d like to see how it works, why not download the source and check it out?

The next tutorial (stay tuned) will cover having multiple widgets accessing the same data model. I’m thinking of having the same simple photo gallery, but adding widgets to allow managing the list of photos.