In its most basic usage, code can be registered to be executed once a single state property becomes truthy or falsy.

SYNTAX

wiringsOBJ = myInstance.once (propertyConditionSTR,handlerFUNC);

The propertyConditionSTR parameter specifies the name of a state property, with an optional "!" (exclamation mark) prefix for indicating condition inversion. If simply the name of a state property is specified, then the handler code specified by the handlerFUNC parameter will be executed once the property is truthy. If the optional "!" prefix is specified, then the handler code will be executed once the property is falsy.

EXAMPLE 1

myWidget.once (
  'wired',
  function () {
    // do something now that the widget has been wired
  }
);

In the above example, a handler is being registered to be executed once the widget myWidget has been wired (i.e. the value of its wired state property becomes true).

EXAMPLE 2

myCollectionWidget.once (
  '!isEmpty',
  function () {
    // do something now that the collection is no longer empty
  }
);

In the above example, code is being registered to execute once the isEmpty state property is false.

Code can be registered to be executed once all properties in a set of state properties become truthy or falsy, by specifying the state properties as an array of property names or as a comma-separated list string.

SYNTAX

wiringsOBJ = myInstance.once (propertiesConditionARRAYorSTR,handlerFUNC);

1.2.1. propertiesConditionARRAYorSTR

1.2.2. Examples

myInstance.once (
  ['phase1Done','phase2Done','phase3Done'],
  function () {
    // execute code now that all three phases are done
  }
);

myInstance.once (
  'phase1Done, phase2Done, phase3Done',
  function () {
    // execute code now that all three phases are done
  }
);

myCollection.once (
  ['wired','!isEmpty'],
  function () {
    // execute code now that the collection widget is wired and no longer empty
  }
);

myCollection.once (
  'wired, !isEmpty',
  function () {
    // execute code now that the collection widget is wired and no longer empty
  }
);

Code can be registered to be executed once a compound condition is met, by specifying the compound condition in the form of a condition function or condition expression string.

SYNTAX

wiringsOBJ = myInstance.once (compoundConditionSTRorFUNC,handlerFUNC);

1.3.1. Condition Function

myFishTankWater.once (
  function (width,height,depth) {return width * height * depth > 1000},
  function () {
    // execute code, now that the water volume of the fish tank exceeds 1000
  }
}

1.3.2. Condition Expression String

myFishTankWater.once (
  'width, height, depth : width * height * depth > 1000',
  function () {
    // execute code, now that the water volume of the fish tank exceeds 1000
  }
}

If the condition specified in the call to the once method is already met at the time that the method is called, then the handler specified by the handlerFUNC parameter will be executed immediately.

Otherwise, handlers will be wired for the Changed.* (value change) events for all the state properties that affect the condition. The condition evaluator will be executed each time any of the watched properties change value. As soon as the condition becomes met (i.e. the condition evaluator produces a truthy result), the handlers wired to watch the value change events of the properties will be unwired and the handler function registered for the condition will be executed. By design, the handler is only executed for the first time that the condition becomes met.

As a convenience, the once method supports condition inversion through an optional "!" (logical not) prefix that can be placed before the condition name.

EXAMPLE

myCollectionWidget.once (
  '!isEmpty',
  function () {
    // do something now that the collection is no longer empty
  }
);

In the above example, code is being registered to execute once the isEmpty state property is false. This is done by prefixing the "isEmpty" condition name with a "!" (bang / exclamation) character to indicate that the code should execute only once the collection is not empty (i.e. the value of the isEmpty state property becomes false). The condition inversion facility is convenient in situations like this where you wish to execute code only once a property's value becomes falsy, rather than once the property's value becomes truthy (which is the standard behavior for the once method).

1.5.1. Condition Inversion with Multiple Property Conditions

myCollectionWidget.once (
  ['wired','!isEmpty'],
  function () {
    // do something now that the collection is wired and no longer empty
  }
);

The once method returns a wirings object that can be supplied to the unwire method in order to unwire the handler, in the unlikely event that one may wish to remove the handler before the condition becomes met.

This case is unlikely to arise except in exceptional situations, but the means is provided. In most cases, you will simply discard / ignore the return value of the once method. In the event that the condition is met when the once method is called, then the returned wirings object will be an empty object.

The handler code that is registered to be executed once a condition is met will be passed the values of all the state properties that affect the condition as arguments.

EXAMPLE

myFishTankWater.once (
  'width, height, depth : width * height * depth > 1000',
  function (width,height,depth) {
    alert (width + '(W) x ' + height + '(H) x ' + depth + '(D)');
  }
}

myFishTankWater.set ({
  width:10,
  height:11,
  depth:12
});

In the above example, code is being registered to be executed once the product of the width, height, and depth properties of the myFishTankWater instance exceeds 1000. Once the call to the set method has been executed, the volume of the fish tank's water will be 1320 and the handler will be executed.

Now, because the properties affecting the condition have been specified as "width, height, depth", the value of these state properties will be passed as arguments to the handler in the order width, height, and depth. In this case, the handler function is choosing to declare these function arguments, using the same names for the sake of clarity - you could ignore the arguments if you didn't care about the specific values at the time the condition is met, or you could use the arguments but name them differently. In this example, the alert statement will alert the text "10(W) x 11(H) x 12(D)".