UIZE JavaScript Framework

2013 NEWS 2013-08-14 - New onChange Instance Method for Classes

The new onChange instance method, implemented in the Uize.Class base class module, provides a way to register a handler that should be executed each time the value of a state properties derivation changes.

SYNTAX

wiringsOBJ = myInstance.onChange (derivationSTRorARRAYorFUNC,handlerFUNC);

The way that this method behaves is best illustrated by an example...

EXAMPLE

// create a Rectangle class with width and height state properties
var Rectangle = Uize.Class.subclass ({
  stateProperties:{
    width:{value:10},
    height:{value:10}
  }
});

// create an instance of the Rectangle class
var rectangle = Rectangle ();

// register a handler for when the computed area changes
// the value "100" will be alerted, since the handler is always executed initially
rectangle.onChange (
  function (width,height) {return width * height},
  function (area) {alert (area)}
);

rectangle.set ({width:20,height:10});  // area changes, so the value "200" will be alerted
rectangle.set ({width:10,height:20});  // area hasn't changed, so nothing will be alerted

In the above example, we are creating a simple Rectangle class with width and height state properties that each have an initial value of 10. After creating an instance of this class, we register a handler for a state properties derivation that is defined to compute the rectangle's area from the values of its width and state properties.

By design, the handler is executed immediately upon first computing the value of the derivation. This results in the text "100" being alerted, which is the rectangle's area at the time of registering the change handler. Next, we call the set method on the rectangle instance, setting the width to 20 and the height to 10. This results in the area changing to 200 and the change handler is executed again, this time alerting the text "200". Finally, we call set one more time, this time setting the width to 10 and the height to 20. Because the area of the rectangle after this set will still be 200, the change handler is not executed again.

1. Change Handler Signature

The handler for a change event can expect to receive the following two parameters...

derived value - the new computed value for the state properties derivation
determinants values - an array, containing the values of all the determinants (i.e. the state properties) used in deriving the value, in the order in which they occur in the definition for the derivation

EXAMPLE

rectangle.onChange (
  function (width,height) {return width * height},
  function (area,determinants) {
    alert ('Area: ' + area + ' (' + determinants [0] + ' x ' + determinants [1] + ')')
  }
);

In the above example, we are registering a handler for a state properties derivation that derives an area value from the width and height state properties of a rectangle instance. In addition to declaring an area argument for the derived value, the handler function is also declaring a determinants argument that can be used to inspect the values of the derivation's determinants (the width and height state properties, respectively). Because the derivation was declared with width first and height second, this will be the order of the properties' values in the array passed via the determinants argument.

1.1. Arguments Optional

While the derived value and determinanrs values parameters will be passed to the handler function, there's no requirement that a handler function declare arguments for them or use them.

In many cases, you may only care to know the new derived value and not need to know the specific values of the determinants. In such cases, your handler function can declare only a single argument for the derived value.

2. Unwiring onChange Handlers

The onChange instance method returns a wirings object, which provides a means with which to unwire all the event wirings associated with registering a handler using this method.