Plugin properties reference

Plugin metadata

These properties define:

• Which version of the Forms Plugin API your plugin is using.
• The plugin author and version that appear in the plugin administration page.

Configuration fields

These properties define fields used to configure the plugin in the Form designer. There are standard fields that are common to all Form controls, and custom fields you can create.

Standard fields

Custom fields

Define custom fields that appear in the configuration panel in the Form designer.

Each custom field is defined as an object within the properties object. See Create a custom configuration field.

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.

Custom fields data types

Custom fields must adhere to a data type. The data type determines how the field's value is treated by Form rules and variables. Some data types provide additional properties, like minimum or maximum values.

properties: {
  intAttr: {
    title: 'Integer field',
    description: 'From 1 - 10',
    type: 'integer',
    minimum: 1,
    maximum: 10,
    defaultValue: 1,
  },
}

properties: {
  numAttr: {
    title: 'Decimal field',
    description: 'From 1 - 10',
    type: 'number',
    minimum: 1,
    maximum: 10,
    defaultValue: 1.23,
  },
}

properties: {
  textAttr: {
    title: 'Text field',
    description: 'Maximum 255 characters',
    type: 'string',
    maxLength: 255,
    defaultValue: 'abc',
  },
}

properties: {
  boolAttr: {
    title: 'Boolean field',
    type: 'boolean',
    defaultValue: true,
  },
}

properties: {
  choiceAttr: {
    title: 'Choice field',
    type: 'string',
	enum: ['Option A', 'Option B', 'Option C'],
    showAsRadio: true,
    verticalLayout: true,
    defaultValue: 'Option A',
  },
}

properties: {
  contactDetails: {
    title: 'Contact information',
    type: 'object',
    description: 'Contact details',
    properties: {
      name:{
        type: 'string',
        description: 'Full name',
        title: 'Name',
      },
      phone: {
        type: 'string',
        description: 'Phone number',
        title: 'Phone number',
      },
    },
  },
}

Custom field properties

Form designer appearance

These properties control how the plugin appears in the Form designer toolbox.

Predefined icons

The predefined icons correspond to the out-of-the-box form controls:

• address-finder
• barcode
• multichoice
• choice
• currency
• data-lookup
• date-picker
• email-outline
• attach
• geolocation
• group-control
• image
• rich-text
• one-line-numbers
• users
• repeating-section
• signature
• space
• multiline-text
• one-line-text

Form designer behavior

This property controls how the plugin behaves when designing the form, such as which plugin fields can be altered by rules or variables.

Form canvas appearance

The designer.canvasRestrictions object defines how your plugin behaves on the Forms canvas.

You can also use CSS variables and custom CSS to style your plugins. See Style plugins with CSS.

Events

To store a value, form plugins must emit a custom event called ntx-value-change to notify the form that their value has changed and should be stored.

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. Provided your plugin has defined a custom field to store the value, the value is automatically stored when your plugin code emits the event. See Store a value in an output variable.

Your plugin can also emit custom events for other changes, such as when an external API call has returned a response, or a calculated value is within a valid range. Form designers may use these events to create Form rules for the plugin, or for other form controls in the same form.

To make custom events available to Form rules, define each custom event name in the Events array at the root level. The event names must match the name of the custom events emitted by your plugin. Only events that are defined in the events array will be available in the Form rules.

Note: You only need to add the ntx-value-change event to the Events array if you want the on-value-change event to be available in Form rules. The ntx-value-change event still stores the plugin's value if it is not defined in the Events array.

For an example of creating custom events in your plugin, see Store a value in an output variable.

Fallback behavior

Note: If your plugin fails to load from your hosting provider, this fallback property will not be read, and your submit button will not be disabled.