Create a plugin with React

In this example, we will use React to build an iframe to display web content from a URL.

We will create one JSX file for the iframe web component and a second JSX file that acts as a wrapper to:

Add the React framework
Use the react-to-webcomponent npm package to convert the react components to a web component
Return the Form plugins contract properties.

Inside the contract properties, we will define the configuration fields that the form designer will use to specify the height of the iframe as well as the URL the iframe should load content from.

Note: Plugins using different versions of React may cause unexpected behavior when they are loaded together in a form. For a React-like framework that offers .jsx and hooks, see Atomico.

Jump to:

You can download the source for this example from the repository.

Create the iframe web component

Create a JSX file Iframe.jsx.
Create a basic iframe web component using React in JavaScript XML.


export const IFrame = ({
  name = "wikipedia",
  title = "Wikipedia",
  src = "https://www.wikipedia.org/",
  height = "100%",
}) => {
  const styles = `
  :host {
    height: 100%;
    width: 100%;
    display: block;
  }
  .frame {
    display: inline-block;
    height: 100%;
    width: 100%;
    background-color: transparent;
    border: none;
  }`;

  const elementStyles = { height: height };

  return (
    <>
      <style>{styles}</style>
      <iframe
        className="frame"
        style={elementStyles}
        name={name}
        title={title}
        src={src}
      ></iframe>
    </>
  );
};

Create the wrapper to add the contract

Create another JavaScript XML file iframeWrapper.jsx.
Import the React components and the iFrame.jsx you created.
Import the react-to-web-component package.
Create a wrapper class that extends the React components and the iframe you created.
Define a custom element using the new class.

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.


import * as React from "react";
import * as ReactDOM from "react-dom/client";
import reactToWebComponent from "react-to-webcomponent";
import { IFrame } from "./Iframe";

class IFrameWrapper extends reactToWebComponent(IFrame, React, ReactDOM, {
  shadow: "open",
  props: ["name", "title", "src", "height"],
}) { 

}

customElements.define("nintex-react-iframe", IFrameWrapper);

Add the contract static function

The static function returns the contract properties that define how the plugin behaves in Nintex forms.

In the wrapper class:

Create a static function getMetaConfig().

  //...
class IFrameWrapper extends reactToWebComponent(IFrame, React, ReactDOM, {
  shadow: "open",
  props: ["name", "title", "src", "height"],
}) {
  static getMetaConfig = () => ({

  });    
}
//...

Define the basic contract configuration

The basic contract configuration defines basic information about your plugin, such as the author and version, and how the plugin should appear in the Form designer.

We will add:

The version of the Forms plugin API it is using.
A description for the plugin in the Form designer.
The icon for the plugin and the control group it should be displayed in in the Form designer toolbox.

We will also add a property to define the fallback behavior if the plugin does not load correctly.

Inside the getMetaConfig() function:

Add a controlName property with the value react-iframe .

This is what the control will be named in the Form design control toolbox.

Add a version property with the value 1.3 .

This uses the version defined in the Form plugin contract.

Add a description property with the value Iframe component which renders content from a source URL .
Add an iconUrl property with the value rich-text .

This uses the icon from the standard rich-text form control.

Add a groupName property with the value Visual .

The plugin will appear in a group called Visual in the Form designer toolbox.

Add a fallbackDisableSubmit property with the value false .

If the plugin does not load correctly, end-users may still submit the form.

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

  //...
static getMetaConfig = () => ({
  controlName: "react-iframe",
  version: "1.3",
  description: "Iframe component which renders content from a source URL",
  iconUrl: "one-line-text",
  groupName: "Visual",
  fallbackDisableSubmit: false,
});
//...

Define the standard configuration fields

Standard fields represent configuration fields that are available to all form controls. You can control which standard fields are available to be configured by form designers by defining the properties here.

Note: Defining a standard field as true does not set the field value to true. For example, setting readOnly to true does not make the plugin read only: it ensures the "read only" configuration field is available to the form designer.

Inside the getMetaConfig() function, add an object called standardProperties.
Inside the standardProperties object:

Define a readOnly property as true.

This property allows the plugin to be configured as read-only when used in a form design.

Define a required property as true.

This property allows the form designer to designate the plugin as being required when designing the form.

Define a description property as true.

This property allows the form designer to provide a description below the plugin when the form is rendered to the end-user.

For more information on standard properties, see Standard fields

//...
static getMetaConfig = () => ({
  //...
  standardProperties: {
    readOnly: true,
    required: true,
    description: true,
  },
});
//...

Define the custom configuration properties

You can add additional fields that are used to configure your plugin. In this example, we're adding two fields so that the designer can specify the source URL they want to display and the height of the iframe.

Custom fields are added using the properties object.

Inside the getMetaConfig() function, add a properties object.
In the properties object, add an object called src with three properties:

type, with a value of string.
title, with a value of Source URL.

The title is displayed as a label for the configuration field.

description, with a value of URL of the content to display. Note that some sites may not allow content to be rendered in an iframe.

The description is displayed below the configuration field.

In the properties object, add an object called height, with three properties:

type, with a value of string.
title, with a value of Height.
description, with a value of Height of the iframe.

For more information on defining custom configuration fields, see Custom fields.

//...
static getMetaConfig = () => ({
  //...
  properties: {
    src: {
      type: "string",
      title: "Source URL",
      description:
        "URL of the content to display. Note that some sites may not allow content to be rendered in an iframe",
    },
    height: {
      type: "string",
      title: "Height",
      description: "Height of the component",
    },
  },
});
//...

The complete plugin contract configuration


import * as React from "react";
import * as ReactDOM from "react-dom/client";
import reactToWebComponent from "react-to-webcomponent";
import { IFrame } from "./Iframe";

class IFrameWrapper extends reactToWebComponent(IFrame, React, ReactDOM, {
  shadow: "open",
  props: ["name", "title", "src", "height"],
}) {
  static getMetaConfig = () => ({
    controlName: "react-iframe",
    version: "1.3",
    description: "Iframe component which renders content from a source URL",
    iconUrl: "one-line-text",
    groupName: "Visual",
    fallbackDisableSubmit: false,
    properties: {
      src: {
        type: "string",
        title: "Source URL",
        description:
          "URL of the content to display. Note that some sites may not allow content to be rendered in an iframe",
      },
      height: {
        type: "string",
        title: "Height",
        description: "Height of the component",
      },
    },
    standardProperties: {
      readOnly: true,
      required: true,
      description: true,
    },
  });
}

customElements.define("nintex-react-iframe", IFrameWrapper);

Build and register the plugin

Your plugin is ready to upload and test:

Build your plugin with the npm command npm run build.
Upload your files to your hosting service.

Ensure CORS is enabled where your plugins are hosted. See Host a plugin.

Note: If you want to add this plugin to your Nintex Automation Cloud tenant, ensure Form plugins are enabled in your tenant by your administrator.

See Add a plugin.