Get Started

How to initialize and use v4.4.1 of the Crema Captcha.

<script src="https://unpkg.com/@cremadesign/captcha@4.4.1/dist/captcha.min.js"></script>

How to Initialize

The following example assumes you are using a FormMail form with default settings. If you'd like to use another form processor or customize defaults like classes and filters, please view the "Settings" section below.

HTML Markup

<!-- Note: Only FormMail forms require the use of data-attributes. -->
<form data-post="https://formprocessor.com" data-captcha data-fetch>
	<div class="mb-3">
		<label>Field Name</label>
		<input type="text" class="form-control" required>
	</div>

	<!-- 2019 Honeypot / Checkbox Placeholder -->
	<div class="checkbox captcha"><input type="text" class="honeypot" autocomplete="off" style="display:none;"></div>
	<div class="d-none" data-alert="status"></div>

	<button type="button" class="btn btn-lg btn-submit disabled" name="submit" disabled>Submit</button>
</form>

Javascript Init

// Default Init
captcha('[data-captcha]');

// Get Plugin Info
var settings = captcha();
console.log(settings);
captcha.version;
captcha.author;

Settings

debug

Type: boolean | string
Default: false

Enables pre-defined console.log debugging and Bootstrap alerts. Useful for debugging captcha, while in development. Accepts true, false, captcha, or data.

userinfo New

Type: boolean
Default: false

Fetches user info like language, location, ip address, host referrer, and user agent from JSON with the provided url endpoint. I usually insert this data into the email body, since it may be useful when profiling future types of spam. A sample php script can be found at /location-data.php.

bootstrap

Type: string
Default: 3 to 5

This string is used when inserting the checkbox captcha. For example, a value of '3' will use Bootstrap v3 markup and the alt-checkbox plugin and a value of '4' will use Bootstrap v4's markup and custom checkboxes. This value is determined automatically, but can be overwritten.

type

Type: string
Default: ""

This value is used when inserting default inputs and debugging info. For example, 'formmail' forms use their own subject, recipient, debugging fields, etc. And 'craft2' forms use a hidden CRAFT_CSRF_TOKEN values, as well as a hacked up message field for better looking user info messages. Accepts formmail, craft2, or generic.

action

Type: string
Default: ""

This customizeable action gets added to the form after it is validated and removed once marked invalid. This helps the plugin prevent bot submissions.

button

Type: string
Default: .btn-submit

Selector for the form's button. We recommend disabling the button by default and switching the button type to "button". That way, the button is only functional once the form is validated.

filters

Type: object
Default: See below

This object contains all enabled filters, as well as any applicable settings objects. All filters are enabled by default:

We've provided a few different options for disabling a filter:

// The Boring Betsy
captcha('[data-captcha]', {
	filters: {
		profanity: false,
		checkbox: false
	}
});

// The Tactful Tactician
captcha('[data-captcha]', {disable: "checkbox,profanity"});

// Sir Setty McSettyham
var settings = captcha();
settings.filters.checkbox = false;
settings.filters.profanity = false;
captcha('[data-captcha]', {settings});

config

Type: object
Default: see below

Some filters have customizeable options, which can be accessed within the config object:

You can replace individual filter options two different ways:

// The Boring Betsy
captcha('[data-captcha]', {
	config: {
		profanity: {
			"url": "https://example.com/badwords.js",
		}
	}
});

// Sir Setty McSettyham
var settings = captcha();
settings.config.profanity.url = "https://example.com/badwords.js";
captcha('[data-captcha]', {settings});

Custom Callbacks

By default, this plugin toggles form actions and button classes when a form is validated. However, developers can override these default actions with "valid" and "invalid" callbacks. Why is this important?

In the example below, the plugin will ignore the provided form action, since a custom callback was provided. When form validates, the custom "valid" function will run. However, if it is marked invalid ... the "invalid" function will fire.

captcha('[data-captcha]', {
    "userinfo": true,
    "valid": function() {
        var form = this,
            action = form.getAttribute("data-post"),
            btn = form.submit,
            alert = form.querySelector('[data-alert="status"]');

        form.action = action;
        form.method = "post";
        btn.classList.remove("disabled");
        btn.disabled = false;
        btn.type = "submit";
        alert.innerHTML = "This form is valid!";
        alert.className = "alert alert-info";
    },
    "invalid": function() {
        var form = this,
            btn = form.submit,
            alert = form.querySelector('[data-alert="status"]');

        form.removeAttribute("action");
        form.removeAttribute("method");
        btn.classList.add("disabled");
        btn.disabled = true;
        btn.type = "button";
        alert.innerHTML = "This form is invalid!";
        alert.className = "alert alert-danger";
    }
});