Enabling recaptcha
It is possible to enable reCaptcha (Google reCaptcha v3) on your forms out of the box. All you have to do is add the enable_recaptcha: true parameter to your form, and add
{% include_plate_scripts "recaptcha_scripts" %}
somewhere on the page that has the form on it. The form will not be submitted if the scripts are not included on the page! You will receive the JS error executeRecaptcha is not defined if you don't. Read more about the include tag.
The form then imports Google's reCaptcha JS API. When the form is submitted, a token is generated and sent with the form to the Plate backend. Before the message is sent, the captcha will be verified by the Plate servers.
Advanced implementation
All this happens with JavaScript that Plate injects in your site. However there are use cases where you are submitting the form programmatically with JS yourself. For example if you want to use HTML5 or JS validation on your form. Obviously the Plate JS code will then interfere with your code. To prevent this, you can change the enable_recaptcha param to
:enable_recaptcha: 'skip_js'.
This still imports all necessary code for the reCaptcha to verify, but the form will not be submitted by Plate's JavaScript anymore. This means you will have to trigger the token generation yourself.
You can call the token generation JS function in your own code: executeRecaptcha. This JS function accepts two arguments:
- The form's DOM object (required)
- A function that will be called after the token is generated (optional)
Example:
var form = document.querySelector("form#your-form-id")
form.addEventListener('submit', function(e) {
e.preventDefault()
// Do your thing
executeRecaptcha(form, function(){
form.submit() // Submit the form after the token is generated.
})
});As you can see the executeRecaptcha function receives two arguments: the form's DOM object and a callback function, that submits the form after the token is generated, so it can be sent with the form to the Plate backend.
executeRecaptcha accepts a form, usually created with the form tag, so you can submit it. It is also possible to only retrieve the recaptcha token, if you want even more flexibilty. This can be done with loadRecaptcha. This can be useful when sending form data to JSON endpoints.
loadRecaptcha('custom-unique-recaptcha-form-action', function(token){
console.log(token) // returns the recaptcha token in the callback
})