Create a simple textfield plugin

In this example, we will create a material textfield plugin that has a configurable property and stores a value as a form variable. We will:

1. Create the web component first using Lit and TypeScript.
2. Add the Form plugin contract to convert the web component to a plugin.
3. Build the plugin JavaScript file using an npm command.

This tutorial uses the @material/mwctextfield npm package.

What is Lit?

Lit is a library for building lightweight web components. For an overview of using Lit to build Form plugins, see Get started with web components and Lit.

To learn more about developing with Lit, see:

• Introduction to Lit (YouTube)
• Introduction to Lit (developer tutorials)
• Lit learning centre

The Lit documentation also provides additional tutorials and a development playground.

 

Create a TypeScript file and import the following:

• html and LitElement from lit
• customElement and property from lit/decorators
• Material text field, along with its styles and the TextField element
• NintexPlugin from the local /lib folder.

Note: This tutorial builds the final plugin JavaScript using npm. The import modules are npm packages and local libraries provided in the Form plugins repository.

1. Using the customElement Lit decorator you imported, create a class that extends LitElement.

Note:  Your plugin element name must contain a hyphen - and must not start with ntx-, nwc-, nac-, or nintex-. These prefixes are reserved to prevent conflicts with Nintex elements. For best practice, use your organization's name as a prefix. For example, acme-custom-textfield.

2. Assign the material textfield styles you imported to a styles variable.
3. Using the property decorator you imported, create four properties:
   • label (non-null string), using the default property options
   • description (non-null string), using the default property options
   • outlined, with a property options type of Boolean, initialized to false
   • readOnly, with a property options type of Boolean, initialized to false.

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.

Plugins use events to pass data to the form. For example, when the user changes the value in a text field, you send an onChange event with the field's new value. The form captures the data in the event to store the new field value.

To add an event to your plugin:

1. Outside the textfield class you created, declare a typed function that creates and dispatches a custom event called ntx-value-change.

Note: The name of the custom event must be ntx-value-change. For more information on supported event names, see Events.

2. Inside the textfield class, create a private onChange() function that calls the typed function on the textfield.

Add a render function to the textfield class that returns the mwc-textfield element you imported, and includes the properties and onChange() event you created in the previous steps.

Note: The mwc-textfield element uses a property called helper for its description text and a property called disabled to flag whether the element is read-only or not. In our render function, we map the plugin's properties to the mwc-textfield properties.

The web component is now complete. To add the form plugin contract, create a static getMetaConfig() function to return a promise of the contract properties.

Add the properties for the plugin's behavior and appearance:

1. Add a controlName property with a value of Material Textfield.

This value will appear in the Form designer control toolbox, and at the top of the configuration pane when the control is configured.

2. Add fallbackDisableSubmit property with a value of false.

Setting this field to false means the user can still submit the form even if this plugin fails to load properly.

3. Add an iconUrl property with the value of one-line-text.

The plugin will use the same icon as a single-line textfield in the Form designer control toolbox.

4. Add a version property with the value of 1 (as a string).

This value identifies the form plugin contract version being used.

For more information, see Form designer appearance in the contract reference.

Define custom fields

The plugin has two custom fields:

• A boolean field, outlined, that controls whether the text field shows an outline.
• A string field, value, that will hold the value input by the user when submitting the form.

Each of these fields have properties that define how they appear and behave in the Form designer configuration pane.

Create a properties object.

1. Add an object called outlined with two properties:
• A type property with a value of boolean.
• A title property with a value of Show outline.

Note: The outlined object must be named identically to its counterpart in the web component property we created earlier.

2. Add an object called value with four properties:
   • A type property with a value of string.
   • A title property with a value of Value.
   • 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.

   • A defaultValue property with a value of This is a text field default value.

   This sets the default value of the custom field.

For more information, see Custom fields in the contract reference.

Define standard fields

Define which standard fields should be available in the control configuration panel. When a field is available, the form designer can configure the field either by form rules, or using the configuration pane.

Create a standardProperties object and add the following properties with a value of true:

• fieldLabel
• description
• defaultValue
• readOnly.

Note:  There is no default behavior provided for any standard fields. When a plugin's standard field is configured, the value of the field is passed to the plugin. Plugins are responsible for implementing any behavior they need for standard fields. In our example, we provide the implementation by mapping the plugin's properties to the mwc-textfield properties in the render() function. See Add the render function.

For more information, see Standard fields in the contract reference.