Logo/Docs

Themes Helper Macros

Overview

FusionAuth has a template that contains a number of macros used in all of the page templates. This template is located at ../_helpers.ftl and it contains a number of FreeMarker macros. The rest of the pages use these macros to generate various pieces of the HTML. The macros contained in _helpers.ftl are:

Section Helpers

Here is an example of what one of these helpers looks like:

HTML helper

[#macro html]
<!DOCTYPE html>
<html>
  [#nested/]
</html>
[/#macro]

The key to these macros is the [#nested/] element. This is the location that FreeMarker will insert any nested content when you use the macro. Here is an example of using this macro:

Example usage of HTML macro

[@helpers.html]
<body>
Hello world!
</body>
[/@helpers.html]

Everything inside the macro will be place where the [#nested/] element is. Therefore, the result of our example would be this HTML:

Example result

<!DOCTYPE html>
<html>
<body>
Hello world!
</body>
</html>

All of the page templates use these macros, which makes it much easier to style all of the pages at one time. You simply edit the macros and your changes will take effect on all of the pages listed above.

Social (alternative) Login Helpers

In addition to the section helpers, the _helpers.ftl template also contains additional macros that can be used to setup social and alternative logins. Currently, FusionAuth supports these social login providers:

This macro can be included on the Authorize or Register page.

Once you have configured your alternative logins (called identity providers in the interface and API), they will appear on the FusionAuth stock login form. This is because our stock login form includes this code:

Social login code

[@helpers.head]
  [@helpers.alternativeLoginsScript clientId=client_id identityProviders=identityProviders/]
  ...
[/@helpers.head]

[@helpers.body]
  ...

  [@helpers.alternativeLogins clientId=client_id identityProviders=identityProviders/]
[/@helpers.body]

The first macro (alternativeLoginScripts) includes the JavaScript libraries that FusionAuth uses to hook up the identity providers. Unless you want to write your own JavaScript or use a third-party library, you will need this JavaScript in the <head> tag in order for FusionAuth to leverage external login providers.

The second macro (alternativeLogins) produces the login buttons for each of the configured identity providers. These buttons are all hooked up to the JavaScript included in the <head> of the page in order to make it all work nicely.

You might want to use your own buttons for social logins. This is possible with FusionAuth, but you will need to do a couple of things to make it all work.

First, you need to remove the [@helpers.alternativeLogins] macro call.

Second, you need to use a specific id or class on your HTML element for the button. Here are the id s or class es for each identity provider:

And finally, you need to ensure that Prime.js is included on your page. This library ships with FusionAuth and you just need to ensure it is included like this:

Prime.js include

<script src="/js/prime-min.js"></script>

Alert and Error Helpers

The _helpers.ftl template also provides a couple of macros that can be used to output errors and alerts that might occur. The best bet is to include these macros in your main macro. Here are the macros and their purpose:

Form Helpers

The _helpers.ftl template provides a couple of macros that help render form elements and output form errors. Here are the macros you can use:

CAPTCHA

The _helpers.ftl template provides a macro to embed CAPTCHA challenges into your templates.

Parameters

captchaMethod[String]

This is the type of CAPTCHA to use. Typically supplied by the tenant.captchaConfiguration.captchaMethod template variable. Valid values are:

  • GoogleRecaptchaV2 - use Google reCAPTCHA v2
  • GoogleRecaptchaV3 - use Google reCAPTCHA v3
  • HCaptcha - use HCaptcha
  • HCaptchaEnterprise - use HCaptcha Enterprise - v25
showCaptcha[Boolean]

This determines whether or not to show the CAPTCHA badge. Typically supplied by the showCaptcha template variable.

siteKey[String]

The data-sitekey value to use for the CAPTCHA. Typically supplied by the tenant.captchaConfiguration.siteKey template variable. Required if using GoogleRecaptchaV3.

Invisible reCAPTCHA

If you wish to enable an invisible reCAPTCHA element so that a CAPTCHA will still challenge a submit without a checkbox on the form you may do so by adding the data-size and data-callback attributes on the tag with the g-recaptcha class. In FusionAuth version 1.46.0 and later these attributes will be present in the default template but commented out.

Invisible tag

[#if captchaMethod == "GoogleRecaptchaV2"]
      <div class="g-recaptcha" data-sitekey="${siteKey!''}"
        data-size="invisible"
        data-callback="reCaptchaV2InvisibleCallback"
      ></div>
 ...

On versions of FusionAuth prior to 1.46.0 you will need to update the JavaScript in order to properly handle the form submit for invisible reCAPTCHA. See this GitHub issue for more information.