UI

The UI object provides a means of adding human readable labels and configuration options to the admin UI. Workflows can be hardcoded or they can be created from the Event and Destination building blocks.

A UI can be as simple as a single label or it can include a description and form fields.

Note the UI object is agnostic about where its data is stored. Getting and setting data should be handled manually for any hardcoded workflows. Workflows created via the admin UI automatically use the workflow post's metadata for storage and retrieval.

Static Methods

register( string $name ) : UI

Creates and returns a UI object instance. These cannot be accessed directly but only via the variable they are assigned to or the Event or Destination object they are attached to.

The $name is the primary label shown in the admin UI.

$ui = UI::register( __( 'Custom event' ) );

Public Methods

set_description( string $description ) : UI

Set an extended description for the UI. This might be some instructions or additional information and context for users.

add_field( string $name, string $label, string $type = 'text', array $params = [] ) : UI

A UI can describe form fields that allow for adding custom configuration data. This means a single Destination or Event object can be used multiple times with different effects.

• $name is the storage key or id of the field, used as a name attribute on a form field.
• $label is the human readable label for the form field
• $type is the field type. The following types are supported by default:
  • text
  • number
  • url
  • checkbox
  • select
  • textarea
• $params is a collection of additional data used to create the field
  • description: An optional string with additional help text
  • For "select" fields only:
    • options: an array of arrays with label and value keys, eg. [ [ 'label' => 'One', 'value' => 1 ] ]
    • multi: boolean, if true multiple items can be selected
    • endpoint: array, this is a dynamic alternative to options with the following keys:
      • url: a REST API endpoint to retrieve options from. Must return an array.
      • labelKey: The property to use for the dropdown labels, default is 'name'
      • valueKey: The property to use for the dropdown values, default is 'ID'

set_data( array $data ) : UI

Set the data for a UI, this is used as a lookup for the field values where the array keys match the $name for an added field.

get_data() : array

Returns the data array for a UI object.

get_field_data( string $name ) : mixed

Retrieve a specific key's value from the UI data supplied in set_data().

get_name() : string

Returns the UI's name property.

get_description() : string

Returns the UI's description property.

get_config() : array

Returns an array describing the UI object in the following shape:

• name
• description
• fields
• data

Adding new field types

If you need a custom field type handler in the UI they can be added via JavaScript by extending the HM.Workflows.Fields global object.

New fields should extend the HM.Workflows.Fields.base React component class. You can find examples of the extended base field in /admin/src/Fields.