Class Control

Returning true does not guarantee that the Control will be selected.

Usage:

• The handling of a request can and should be contextual. That is, a control should only return canHandle = true if the request makes sense for the current state of the control.

• A @see ContainerControl should return true if one or more of its children returns canHandle = true. Thus the root of a Control tree should return canHandle = true unless the request cannot be meaningfully consumed by any Control in the tree.

• The implementation should be deterministic and effectively memoryless. i.e. no state changes should be made that would be exposed by getSerializableState().

Usage:

• A control should only return canTakeInitiative = true if the control, in its current state, has something important to ask of the user. This could be a necessary elicitation, clarification, confirmation or some other activity to obtain and finalize the information managed by the Control.

• A @see ContainerControl should return true if one of its children returns canTakeInitiative = true or if the container needs to ask the user a question directly. Thus the root of a Control tree should return canTakeInitiative = true if any control in the entire tree reports canTakeInitiative = true.

• The implementation should be deterministic, idempotent, and effectively memoryless. Effectively memoryless means that any state changes are temporary and will not be exposed in the serialized state.

Framework behavior:

• The initiative phase runs if the handling phase did not produce a responseItem that has .takesInitiative = true.

Only durable state should be included and the object should be serializable with a straightforward application of JSON.stringify(object).

Default: {return this.state;}

Usage:

• This method must be idempotent (multiple calls must not change the result).
• The default is sufficient for Controls that use the .state variable and only store simple data.
  • Non-simple data includes functions, and objects with functions, as these will not survive the round trip.
  • Other non-simple data include types with non-enumerable properties.
• It is safe to pass the actual state object as the framework guarantees to not mutate it.
• Functions that operate on the Control's state should be defined as member function of the Control type, or as props.

Framework behavior:

• During the shutdown phase the state of the control tree is collected by calling this function for each control.
• The framework serializes the data use a simple application of JSON.stringify.
• On the subsequent turn the control tree is rebuilt and the state objects are re-attached to each Control via control.setSerializableState(serializedState).

Handling a request involves orchestrating state changes to the Control (and its children) and adding response items to the ControlResultBuilder.

Note:

• A basic invariant is isReady === !canTakeInitiative because isReady implies that no further discussion is required and thus there is no need to take the initiative.

Default implementations:

• Control: reestablishes the state via this.setSerializableState(state).
• ContainerControl: reestablishes the state and recursively reestablishes state for all children.
• DynamicContainerControl: reestablishes the state, rebuilds any dynamic child controls, and recursively reestablishes state for all children.

This is intended to be used to provide APL rendering component for a control to process inputs, provide feedback, elicitation etc through touch events on APL screens.

This is intended to be used with the default ControlManager.render() which implements a simple concatenation strategy to form a complete response from multiple result items.

Default: {this.state = serializedState;}

Usage:

• This method must be idempotent (multiple calls must not change the result).
• It is safe to use serializedState without copying as the framework guarantees to not mutate it.

Framework behavior:

• During the initialization phase the control tree is rebuilt and state objects are re-attached to controls by calling this method for each control.

Framework behavior:

• The initiative phase runs if the handling phase did not produce a responseItem that has .takesInitiative = true.