Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Control

Abstract base class for Controls.

Purpose:

  • this class provides a simpler way to define a control than direct implementation of IControl. Various default implementations are provided.

Usage:

  • Define new control types by sub-classing this abstract class and providing implementations for the abstract methods.
  • If the custom control will have children, sub-class ContainerControl instead.

Hierarchy

Implements

Constructors

constructor

  • Parameters

    • id: string

    Returns Control

Properties

Readonly id

id: string

state

Methods

Abstract canHandle

  • canHandle(input: ControlInput): boolean | Promise<boolean>
  • Determines if the Control or one of its children can consume a request.

    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().

    Parameters

    • input: ControlInput

      Input object. input.request contains the request to be handled.

    Returns boolean | Promise<boolean>

    true if the Control or one of its children can consume the entire request, false otherwise.

Abstract canTakeInitiative

  • canTakeInitiative(input: ControlInput): boolean | Promise<boolean>
  • Determines if the Control can take the initiative.

    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.

    Parameters

    Returns boolean | Promise<boolean>

    true if the Control or one of its children can take the initiative, false otherwise.

evaluateAPLProp

  • Evaluate an APL document/data source prop.

    Parameters

    • act: SystemAct

      act

    • input: ControlInput

      The input object

    • propValue: object | function

      Constant or function producing a map of key:value pairs

    Returns object

    • [key: string]: any

evaluateBooleanProp

  • evaluateBooleanProp(propValue: boolean | function, input: ControlInput): boolean
  • Evaluate a boolean prop.

    Parameters

    • propValue: boolean | function

      Constant or function producing boolean

    • input: ControlInput

      The input object

    Returns boolean

evaluateFunctionProp

  • evaluateFunctionProp<T>(prop: T | function, input: ControlInput): T
  • Type parameters

    • T

    Parameters

    Returns T

evaluatePromptProp

  • Evaluate a prompt prop.

    Parameters

    Returns string

getSerializableState

  • getSerializableState(): any
  • Gets the Control's state as an object that is serializable.

    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).

    Returns any

    Serializable object defining the state of the Control

Abstract handle

  • Handles the request.

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

    Parameters

    • input: ControlInput

      input.request contains the request to be handled.

    • resultBuilder: ControlResultBuilder

      Collect SystemActs that represent the system output.

    Returns void | Promise<void>

isReady

  • Determines if the Control's value is ready for use by other parts of the skill.

    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.

    Parameters

    Returns Promise<boolean>

    true if the control has no further questions to ask the user such as elicitation, clarification or confirmation.

reestablishState

  • reestablishState(state: any, controlStateMap: object): void
  • Reestablishes the state of the control.

    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.

    Parameters

    • state: any
    • controlStateMap: object
      • [index: string]: any

    Returns void

renderAPLComponent

  • Add response APL component by this control.

    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.

    Parameters

    Returns object

    • [key: string]: any

renderAct

  • Add response content for a system act produced by this control.

    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.

    Parameters

    Returns void

setSerializableState

  • setSerializableState(serializedState: any): void
  • Sets the state from a serialized state object.

    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.

    Parameters

    • serializedState: any

      Serializable object defining the state of the Control

    Returns void

Abstract takeInitiative

  • Takes initiative by adding an InitiativeAct to the result.

    Framework behavior:

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

    Parameters

    Returns void | Promise<void>

throwUnhandledActError

  • throwUnhandledActError(act: SystemAct): never
  • Parameters

    Returns never