Store a value in an output variable

Your plugin may need to return a value to the form. Values may be used for form rules and formulas, or used in a workflow as a form variable.

Jump to:

To return a value from your plugin to the form:

  1. Create a custom event called ntx-value-change that is emitted by your plugin.

    2. An event with this name automatically notifies the form that your plugin's value has changed.

  2. Add code to your plugin to fire the event when you want the plugin's value to be stored.
  3. Add a custom field with a property of isValueField: true to your plugin's getMetaConfig() function.

    4. The value will be stored in this property.

For more information on plugin properties, see Plugin properties reference.

Note: Most examples in this documentation use the reactive properties feature of the Lit framework. When a property is reactive, as denoted by @property() , Lit creates a getter and setter pair for the property and schedules a DOM render whenever the property is changed. If you are not using Lit or a similar framework that offers this functionality and you want the plugin to update when properties are changed, you will need to implement this yourself. For more information on using Lit, see Get started with web components and Lit.

Create a custom event called ntx-value-change

Your plugin must emit a custom event called ntx-value-change to notify the form its value has changed and should be stored. The plugin's value will be automatically available to Form rules and formulas. The event should be emitted by your plugin's code whenever a new or changed value for the plugin should be stored.

Note: The name of the custom event must be ntx-value-change for your plugin's value change to be detected and stored, and for the value to be available to Form rules and formulas. For more information on supported event names, see Events.

The following is an example implementation of the custom event. The code required for your plugin may be different.

//...
onChange(e) {
    const args = {
        bubbles: true,
        cancelable: false,
        composed: true,
        // value coming from input change event. 
        detail: e.target.value,
    };
    const event = new CustomEvent('ntx-value-change', args);
    this.dispatchEvent(event);
}

Add a custom field

To add a custom field to store the value:

  1. In the getMetaConfig() function, add an properties object if one is not already defined.
  2. Inside the properties object, add an object called value with three properties:
    • A type property with a value corresponding to your plugin's data type.

      • See Custom fields data types.

    • A title property with a value of Value.

      • You may use a different value for your title if appropriate.

    • An isValueField property with a value of true.

    This marks this custom field as containing the value the plugin should return to the form. Only one custom field in your plugin can use this property.

We recommend using the name value for this object to make it easy to identify which field holds the plugin's stored value, but you can use another name if that would be more suitable for your plugin.

See Custom field properties.

export class SampleTextfield extends LitElement {
  //...
  static getMetaConfig() {

    return {
      //...
      properties: {
        value: {
          type: 'string',
          title: 'Value',
          isValueField: true,
        },
      },
    };
  }

Note: ntx-value-change is a special event name reserved for notifying the form that the plugin's value has changed and should be stored. The stored value is automatically available to Form rules and formulas. If your plugin emits other custom events that you want to make available to Form rules and formulas, these events must be added to the events array. See Events.