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.

  4. If you want the value to also be available for form rules, add the event to the plugin's contract properties.

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 event should be emitted by your plugin's code whenever a new or changed value for the plugin should be stored.

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

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

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

See Custom field properties.

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

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

Add the event to the contract

You can make your plugin's value available to rules and formulas. This means form designers can:

  • Update your plugin's value based on other form values.
  • Trigger form behavior based on the value of your plugin.
  • Use your plugin's value in formulas for calculated values.

This step is optional. By default, your plugin's value is not available to Form rules or formulas.

To make the plugin's value available for form rules and formulas, add the custom event to the events array:

  1. In the getMetaConfig() function, add an events array if one is not already defined.
  2. Inside the events array, add the value ntx-value-change.

See Events.

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

    return {
      //...
      properties: {
        value: {
          type: 'string',
          title: 'Value',
          isValueField: true,
        },
      },
      events: ["ntx-value-change"],
    };
  }