Implement a Captcha Custom Form Element using a Third Party Library

Implementing a custom form element allows you to augment the existing form elements that come with Geocortex Workflow.

This article will walk you through creating a form element that uses the react-google-recaptcha component to implement a captcha to distinguish humans from bots.

Prerequisites#

Follow the instructions in the Web Applications SDK page to set up your development environment.

note

A working knowledge of TypeScript is recommended before extending Workflow for web-based hosts.

Overview#

Implementing a captcha custom form element for web applications using a third party library consists of the following steps:

Obtaining a Google reCAPTCHA v2 Site Key
Adding third party library dependencies to your project.
Creating the custom form element.
Implementing the custom form element using the third party library.

Google reCAPTCHA#

The react-google-recaptcha component uses reCAPTCHA technology from Google.

Open Google reCAPTCHA in a web browser.
Sign in with your Google account.
Register a new Site.
Select the reCAPTCHA v2 type.
Select the "I'm not a robot" tickbox option.
Add the domain(s) where your web application is hosted.
This generates a Site Key. Copy this value, it will be required later.

Adding Dependencies#

Run npm install react-google-recaptcha in the terminal to install the third party react-google-recaptcha component.
Run npm install @types/react-google-recaptcha in the terminal to install type information for the third party component. This is optional, but it provides an improved developer experience.

Set up Custom Form Element Skeleton#

To create a new form element:

Open the Workflow activity SDK in Visual Studio Code.
Run npm run generate in the terminal.
When prompted, select Form Element.
Enter the name of the form element you would like to create and press Enter. For example, Captcha.
Open the newly created src/activities/Captcha.tsx file.

Implement the Custom Form Element#

Modify the skeleton form element implementation in src/activities/Captcha.tsx to match the following example.

src/activities/Captcha.tsx

import * as React from "react";
import ReCAPTCHA from "react-google-recaptcha";
import {
    CustomFormElementProps,
    RegisterCustomFormElementBase,
} from "@geocortex/workflow/runtime/app/RegisterCustomFormElementBase";

/**
 * A simple React Component that displays a captcha input.
 * @param props The props that will be provided by the Workflow runtime.
 */
const Captcha = (props: CustomFormElementProps) => {
    const handleChange = (token: string | null) => {
        // Set the value and raise the changed event.
        props.element.value = token ?? undefined;
        props.raiseEvent("changed", token);
    };

    const handleExpired = () => {
        // Clear the value and raise the changed event.
        props.element.value = undefined;
        props.raiseEvent("changed", undefined);
    };

    return (
        <ReCAPTCHA
            sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"
            onChange={handleChange}
            onExpired={handleExpired}
        />
    );
};

/**
 * @displayName Register Captcha Form Element
 * @category Custom Activities
 * @description Registers a Captcha form element.
 */
export class RegisterCaptchaElement extends RegisterCustomFormElementBase {
    /** Perform the execution logic of the activity. */
    execute() {
        this.register("Captcha", Captcha);
    }
}

Update the sitekey on the <ReCAPTCHA> element to use your own site key.

return (
    <ReCAPTCHA
        sitekey="YOUR-SITE-KEY-GOES-HERE"
        onChange={handleChange}
        onExpired={handleExpired}
    />
);

important

The sitekey included in this tutorial is for demonstration purposes only. It is watermarked and will not produce valid captcha results. You must use your own site key.

Deploy the Form Element#

Follow the instructions to build and deploy the activity pack.

Test the Form Element#

Once your activity pack is hosted and registered, your Register Captcha Form Element custom activity should appear in the activity toolbox in Geocortex Workflow Designer alongside the built-in activities.

To use your custom form element in a workflow:

Add your Register Captcha Form Element custom activity to your workflow so that it runs before any Display Form activities that will use the custom form element.
Select the Display Form activity that you want to include your form element in.
Add a Custom form element to the form.
Set the Custom Type property of the Custom form element to Captcha.
Test your workflow.