ibm-js/deliteful — pull request #134 by asudoh (2014-05-30 08:41:58+00:00)
Title: Introduction of Stateful#observe().

The new `Stateful#observe()` returns an observer (`Stateful.PropertyListObserver`) that is API-compatible to [Polymer observe-js](https://github.com/Polymer/observe-js#observable). `Stateful.PropertyListObserver` has most of the features of delite/Invalidating, except event emission. I didn't see the event emission feature is actually used anywhere, but anybody who sees an actual use case please speak up. I foresee most of the use cases of event emission can be achieved by observing for properties.

Widgets can set up an observer for computed property and an observer for UI rendering, by the following:

```javascript
// Computed properties
(this._hComputing = this._hComputing || this.own(this.observe(this.refreshProperties))[0]).addProperties(
"value",
"min",
"max"
);
// UI rendering
(this._hRendering = this._hRendering || this.own(this.observe(this.refreshRendering))[0]).addProperties(
"value",
"min",
"max",
"message",
"displayExtMsg",
"fractionDigits"
);
// Makes sure computed properties calculation happens before UI rendering observer callback
this._hRendering.addDependants(this._hComputing);
```

Other features in `Stateful` and `Stateful.PropertyListObserver` corresponding to delite/Invalidating features are:

* `delite/Invalidating#invalidateProperties(name)` and `delite/Invalidating#invalidateRendering(name)`: `Stateful#notifyCurrentValue(name)`, which creates a pending change record even if there is no change in value.
* `delite/Invalidating#validateProperties()` and `delite/Invalidating#validateRendering()`: `Stateful.PropertyListObserver#deliver()` (e.g. `this._hComputing.deliver()` and `this._hRendering.deliver()`), which synchronously calls observer callbacks for pending change records.

I made change to widgets for proof-of-concept (Intern automation seems to run fine for those changed widgets):

* deliteful/StarRating (The simplest case, only with UI rendering callback)
* deliteful/ProgressBar (A simple case with computed property callback in addition to UI rendering callback)
* delite/FormWidget, delite/FormValueWidget and deliteful/Slider (A case where property list for UI rendering callback is specified in multiple places in a widget)

The upcoming plan is:

* Once this PR looks fine for the stakeholders (and merged), change the remainder of delite/Invalidating-based widgets
* Once the team sees `Stateful#observe()` performance (for `Stateful#watch()` use case) is fine with Android device, change `Stateful#watch()` usage (esp. template code)