It can also be used with the Login Extra as a preHook, as of version 1.0.0
Version 2+ updates the base Google Recaptcha class to the latest 1.1.2, including autoloading and cURL support. https://github.com/google/recaptcha
You must generate API keys for your domain here: https://www.google.com/recaptcha/admin and enter them into the System Settings before you can use ReCaptchaV2. IMPORTANT: You must choose V2 or V3 in the ReCaptcha admin, when generating your client keys. You can use both V2 and V3 on a single MODX install with this Extra—there are separate system settings for V2 and V3.
For some quick start examples and implementation guide, go here.
Designed to be used as a FormIt or Login hook. The hook stops form processing and returns an error if the Recaptcha challenge fails. Use with Google Recaptcha Version 2.
Renders the Recaptcha form element for Google Recaptcha Version 2 validation.
Designed to be used as a FormIt or Login hook. The hook stops form processing and returns an error if the Recaptcha challenge fails. Use with Google Recaptcha Version 3.
Renders the Recaptcha form element for Google Recaptcha Version 3 validation styles.
[[!FormIt?
&hooks=`recaptchav3,email`
...
]]
(V3)
[[!Login? &preHooks=`recaptchav2`]]
(V2)
You will also need to call the accompanying form element renderer snippet somewhere in your html form, for example:
<div class="form-item">
[[!recaptchav3_render]]
[[!+fi.error.recaptchav3_error]]
</div>
(V3)
Example with non-default template Chunk:
<form id="my-unique-form-id">
[[recaptchav3_render?
&tpl=`recaptchav3_submit_html`
&form_id=`my-unique-form-id`
]]
[[!+fi.error.recaptchav3_error]]
<!-- other form elements. needs submit button -->
</form>
In version 3.3.0 a sample Chunk was packaged for triggering Recaptcha on form submit rather than on page load. With this implementation the form element MUST have a id
attribute matching the form_id
parameter in the Snippet call.
As of 2.3+, you can use the "Invisible Recaptcha" implementation:
<form id="login-form">
[[!recaptchav2_render?
&tpl=`recaptchav2_invisible_html`
&form_id=`login-form`
]]
</form>
(V2)
In this usage, the "recaptchav2_invisible_html" Chunk renders a button with the necessary data attributes to trigger ReCaptcha. NOTE: the JavaScript implementation in the Chunk requires the &form_id
to be defined.
As of 3.1+, support for multiple forms in RecaptchaV3 is improved. The threshold for a passing verification score can be customized per Snippet call with the recaptchav3.threshold
property.
<h2>Form Test 1</h2>
[[!FormIt?
&hooks=`recaptchav3,FormItSaveForm`
&validate=`testing1:required:minLength=^12^`
&formName=`form-test-1`
&recaptchav3.token_key=`token-1`
&recaptchav3.action_key=`action-1`
&recaptchav3.threshold=`0.9`
&submitVar=`submit1`
]]
<form action="[[~[[*id]]? &scheme=`full`]]" method="POST">
[[!+fi.error.testing1]]
<input type="text" name="testing1" value="[[!+fi.testing1]]">
<input type="submit" name="submit1" value="submit">
[[!recaptchav3_render?
&tpl=`recaptchav3_html`
&token_key=`token-1`
&action_key=`action-1`
]]
[[!+fi.error.recaptchav3_error]]
</form>
<h2>Form Test 2</h2>
[[!FormIt?
&hooks=`recaptchav3,FormItSaveForm`
&validate=`testing2:required:minLength=^12^`
&formName=`form-test-2`
&recaptchav3.token_key=`token-2`
&recaptchav3.action_key=`action-2`
&recaptchav3.threshold=`0.5`
&submitVar=`submit2`
]]
<form action="[[~[[*id]]? &scheme=`full`]]" method="POST">
[[!+fi.error.testing2]]
<input type="text" name="testing2" value="[[!+fi.testing2]]">
<input type="submit" name="submit2" value="submit">
[[!recaptchav3_render?
&tpl=`recaptchav3_html`
&token_key=`token-2`
&action_key=`action-2`
]]
[[!+fi.error.recaptchav3_error]]
</form>
The render snippet may or may not be usable as a preHook for FormIt at this time. NOTE: you can customize the behaviour of your ReCaptcha implementation, in accordance with Google's developer documentation, by customizing the Chunks used for rendering. You can specify any Chunk in the &tpl
property of the "recaptchav{n}_render" Snippets.
This Extra is maintained in Github: https://github.com/sepiariver/recaptchav2 Bug reports, comments and suggestions welcome.