The change event handler

The change function is called when there is a change in binding or configuration data.

Usage

Use this function to react to changes to binding or configuration data. If this function is not implemented, the view() function is called instead.

The event object

The function takes a single event object that indicates what field the user changed and its new value.

Table 1. Properties of the event object
Property	Type	Description
type	String	Valid values are "binding" and "config". The default value is "binding". If the value is not "config", then it is "binding" by default.
property	String	The property that was changed
oldVal		For simple types, the previous value
newVal		new value
insertedInto	integer	For arrays, the index where the object was added to the list
removedFrom	integer	For arrays, the index where the object was removed from the list

Sample change event

The following change event code is from the Output Text stock control. The code checks if a configuration property has changed, and updates the view with the new value. At the end, it calls the view() change event.

 1 if (event.type == "config") {
 2 	if (event.property == "_metadata.label") {
 3 		var label = this.context.element.querySelector(".outputTextLabel > label");
 4 		label.innerHTML = this.context.htmlEscape(event.newVal);
 5 	} else if (event.property == "_metadata.helpText") {
		var label = this.context.element.querySelector(".outputTextLabel > label");
		label.title = event.newVal;
	}
} else {
	var newData;
	if (event.newVal != undefined) {
		newData = event.newVal;
	} else {
		newData = "";
	}
 6 	this.context.element.getElementsByTagName("span")[0].innerHTML = this.context.htmlEscape(newData);
}

 7 this.view();

The code shown in this change() function executes the following logic:

1 If the change event type is "config", execute the code. Note that if the type is not "config", the event type is "binding".
2 Checks if the label property has changed.
3 Using css query selector, finds the element with class .outputTextLabel, and its child element label (outputTextLabel is the class name on the html element).
4 Set the label to the new text.
5 Run the same code as steps 1 to 5 for the helpText property.
6 Set the contents of the html span element to the new value.
7 Call the view() event handler to reuse code used during initial load/creation and when changes occur.