Interaction Model

This page explains how component plug-ins work with interface variables and the interface evaluation lifecycle. You should have a good understanding of how to work with components and variables. For more advanced background you can read about the details of the interface evaluation lifecycle.

Overview

The key events in a component's lifecycle are:

  1. The component is loaded
  2. The component receives an updated value from the interface
  3. The component saves a value back to the interface

Loading the Component

Your component can be loaded in two ways:

  1. When the interface is first loaded
  2. When the component is shown as a result of a re-evaluation (For example: showWhen becomes true)

When your component is loaded:

  1. Each parameter expression is evaluated (e.g.: from a literal value, a local variable, a rule, etc.)
  2. The interface loads your component's html-entry-point file, which then loads resources and runs scripts defined in the HTML.
  3. The function registered using Appian.Component.onNewValue is called with the evaluated input parameter values.
  4. Your component validates the parameter values and (if all necessary values are provided) initializes any internal state and renders the appropriate view for the user.

Your component will continue to execute as long as it's visible on the interface. If your component is hidden and then shown again or if the entire interface is reloaded, then a new instance of the component is loaded by the interface.

Receiving an Updated Value

Parameter values can change as the user interacts with the rest of the interface (e.g.: the user updates another field that saves its value into a local variable used by your component).

The entire process looks like this:

  1. A parameter value changes as a result of an interface re-evaluation
  2. The function registered using Appian.Component.onNewValue is called with the newly evaluated input parameter values
  3. Your component determines what changes are needed (if any) and renders the updated view for the user

Note: All parameter values are passed in, not just the updated values. If you need to identify the values that changed you'll need to track current parameter values in your code for comparison.

Saving a Value

Users can interact with your component in many ways. Depending the design of your component, users might be able to:

  • Enter a value in an input field
  • Click a button
  • Drag and drop a file

When users interact with your component you can save updated values back to the interface so that those values can be used by other components or can be passed to a smart service function.

The process of saving a value looks like this:

  1. The user interacts with your component
  2. Your component determines if this represents a new value that should be saved back to the interface
  3. Your component calls Appian.Component.saveValue, passing in the new value for a specific input-output or event parameter.
  4. The interface re-evaluates, using the new value to update the local variable, a!save() expressions, or smart service function specified for that parameter.

Warning: Avoid creating loops when saving values.

FEEDBACK