Service Variables

The service variables provide access to integrations within BranchCMS. Currently, they provide methods to work with Google reCAPTCHA version 3.

The following variables are available.

Variable Description
_core.service.recaptchaV3

Holds data and methods to work with Google reCAPTCHA version 3 in site templates.

Google reCAPTCHA V3

You can use the _core.service.recaptchaV3 variables in your templates to test for support of Google reCAPTCHA version 3, configure the reCAPTCHA and output the reCAPTCHA fields and Javascript.

The _core.services.recaptchaV3 variable is an array that holds the same information that the form.captcha variable does. The major difference is that the Javascript code to call grecaptcha.execute() is automatically run with _core.services.recaptchaV3.

Typically you use the _core.service.recaptchaV3 variable outside of form templates and use the form.captcha variable within form templates.

The following variables are available.

Variable Description
_core.service.recaptchaV3.action

The reCAPTCHA page action to record.

You set a default action for all uses of the reCAPTCHA V3 when you configure it.
_core.service.recaptchaV3.error

The error message if the reCAPTCHA does not validate.
_core.service.recaptchaV3.errorCode

The error code if the reCAPTCHA does not validate.
_core.service.recaptchaV3.failed

Boolean value on whether the reCAPTCHA validation failed.
_core.service.recaptchaV3.input

The hidden form field that will hold the reCAPTCHA token to submit with the form. This has to be within the opening and closing form fields. This variable is actually a form field object so you can interact with it like you would with other form fields.

It will be automatically outputted with the {{ _core.service.recaptchaV3.tag }} variable. Or, you can output it directly with the {{ _core.service.recaptchaV3.input.tag }} variable.

If you use {{ _core.service.recaptchaV3.input.tag }} do not also use {{ _core.service.recaptchaV3.tag }} as the field will then be included twice.
_core.service.recaptchaV3.isUsable

A boolean value on whether or not the reCAPTCHA V3 has been set up and enabled.
_core.service.recaptchaV3.js

The Google reCAPTCHA Javascript file that needs to be loaded onto the page.

You can manipulate it by changing the {{ _core.service.recaptchaV3.js.src }} value.

{% set _core.service.recaptchaV3.js.src = _core.service.recaptchaV3.js.src ~ '&callback=myCallback' %}

The <script> tag to output the Javascript file is automatically included in the {{ _core.service.recaptchaV3.tag }} variable. Or, you can output it directly with the {{ _core.service.recaptchaV3.js.tag }} variable.

If you use {{ _core.service.recaptchaV3.js.tag }} do not also use {{ _core.service.recaptchaV3.tag }} as that will cause the Javascript file to be loaded twice.

You can also set it to be outputted with other Javascript files.

{% do _page.addJs(_core.service.recaptchaV3.js.src) %}
_core.service.recaptchaV3.script

This holds the default Javascript that will be outputted with the {{ _core.service.recaptchaV3.tag }} variable. It includes a Javascript Promise that will execute the reCAPTCHA to validate the form.

You can output it as a string:

{{ _core.service.recaptchaV3.script }}

Or, you can treat it as an array and access its values as described below.
_core.service.recaptchaV3.script.function

This holds the Javascript Promise function name that your code will need to use to call the Javascript Promise when the form is submitted. The name is randomly generated each time the page loads.

{{ _core.service.recaptchaV3.script.function }}
_core.service.recaptchaV3.script.js

This outputs the same Javascript used with {{ _core.service.recaptchaV3.script }} but without the <script></script> tags.

{{ _core.service.recaptchaV3.script.js }}
_core.service.recaptchaV3.script.tag

This provides another way to output the default Javascript that will be outputted with the {{ _core.service.recaptchaV3.tag }} variable. It includes a Javascript Promise that will execute the reCAPTCHA to validate the form.

The following tags output the same value:

{{ _core.service.recaptchaV3.script }}

{{ _core.service.recaptchaV3.script.tag }}
_core.service.recaptchaV3.sitekey

This holds the Google reCAPTCHA API site key.
_core.service.recaptchaV3.tag

This will output the default reCAPTCHA tag. It includes the hidden form field that holds the reCAPTCHA token and the Javascript Promise that will execute the reCAPTCHA.
_core.service.recaptchaV3.type

This holds the reCAPTCHA type. For reCAPTCHA V3 the value is "recaptchaV3".

Example usage of the Google reCAPTCHA V3 tags

Google recommends that the reCAPTCHA script is displayed on all pages. Below is an example of how you can do that. We often place this code in either a "footer" snippet template, or a site template near the closing </body> tag. It should be placed before any other Javascript is output in the template.

{# Do this before you output any inline Javascript in the footer #}
{% if _core.service.recaptchaV3.isUsable %}
    {% if _page.hasJs('recaptchaV3') == false %}
        {% do _page.registerJs('recaptchaV3') %}
        {{ _core.service.recaptchaV3.js.tag }}
        {{ _core.service.recaptchaV3.script.tag }}
    {% endif %}
    {% inlinecss %}
        .grecaptcha-badge { visibility: hidden; }
    {% endinlinecss %}
{% endif %}
{# Output any inline Javascript or script tags added to the page #}
{{ _page.js() }}
{{ _page.bodyEndCode() }}
</body>

See the Google reCAPTCHA V3 page for more examples.