Designing Recordable Controls

This section describes how to design a custom GUI control to be compatible with the Test Recorder and GIPP and GITAK playback. A custom GUI control is typically a subclass of jsx3.gui.Block with functionality that is not part of the standard GI library of controls.

Model Events

The custom control must use General Interface model events in the following ways:

• A model event must be published after any user interaction that changes the state of the control. This type of published event must define the event property _gipp and set it to be equal to 1.
• All events that the control publishes and which may have an arbitrary number of subscriptions must be published as a model event.

A model event is published with the method jsx3.gui.Interactive.doEvent().

The following example shows a method that is called when the user clicks on a hypothetical control.

ClickCounter.prototype._ebClick = function(evt, elm) {
  if (this.value == null) this.value = 0;

  var newValue = this.value++;
  var veto = this.doEvent("click", {oldVal:this.value, newVal:newValue});

  if (veto !== false) {
    this.value = newValue;
    this.doEvent("change", {newVal:newValue, _gipp:1});
  }
}

The first published model event, click, allows the event handler to veto the change in value that occurs by default when the user clicks on the control. It does not necessarily indicate a change in value of the control, so it does not define the _gipp property.

The second published model event, change, indicates that the control state did change, so it defines the _gipp property. This ensures that the event is recorded by the Test Recorder even if no event handlers are registered for the change event.

Playback

The custom control must include code that replays the recorded events and changes its own state as if the event were caused by a real user interaction. This code is invoked by GIPP or GITAK during test replay.

To replay the recorded event, implement a replayEvent() method in the control's class, as in the following example.

ClickCounter.prototype.replayEvent = function(objEvent) {
  if (objEvent.subject == "change") {
    // handle the change event by changing the control value
    this.value = objEvent.newVal;
    this.doEvent(objEvent.subject, objEvent);
  } else {
    // handle click and other events that don't affect the control state
    this.doEvent(objEvent.subject, objEvent);
  }
}

In this example, the replay logic sets the value of the control to the value of the newVal event property, which was set in the first code example when the change event was published. Typically, this method also calls doEvent() in case there are any subscriptions on the event.

In this case, the newVal event property is necessary to replay the event properly. Without this property, the change in application state that occurs when the event is recorded can not be applied when the event is replayed. There must be similar cooperation between the code that publishes an event (with _gipp:1) and the code in replayEvent() that replays the event.