FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    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

    • html

      • Renders the <html> element

    • head

      • Renders the <head> element and everything inside it including the <title>, CSS, Java Script, and meta information

    • body

      • Renders the <body> element

    • header

      • Renders any type of header for each page. This could be a navigation bar, side bar, or page details

    • main

      • Renders the main content body of each page. If all of your pages will have similar HTML elements like a container, this is the place to put them.

    • footer

      • Renders the footer content of each page. This might contain links, nav, privacy policies, etc.

    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:

    • Apple

    • Epic Games

    • Facebook

    • Google

    • HYPR

    • LinkedIn

    • Sony PlayStation Network

    • Steam

    • Twitch

    • Twitter

    • Xbox

    • Generic OpenID Connect

    • Generic SAML v2

    • Generic SAML v2 Identity Provider Initiated

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

    • /oauth2/authorize

    • /oauth2/register, available since 1.28.0

    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:

    • id="apple-login-button" is used for Apple

    • id="epicgames-login-button" is used for Epic Games

    • id="google-login-button" is used for Google

    • id="facebook-login-button" is used for Facebook

    • id="linkedin-login-button" is used for LinkedIn

    • id="sonypsn-login-button" is used for Sony PlayStation Network

    • id="steam-login-button" is used for Steam

    • id="twitch-login-button" is used for Twitch

    • id="twitter-login-button" is used for Twitter

    • id="xbox-login-button" is used for Xbox

    • class="openid login-button" is used for Generic OpenID Connect

    • class="samlv2 login-button" is used for Generic SAML v2

    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:

    • printErrorAlerts

      • This outputs any error alerts. These are normally displayed at the top of the page and you might want to make them able to be dismiss (i.e. removed from the page).

    • printInfoAlerts

      • This outputs any informational alerts. These are the same as the errors, but might have different CSS.

    • alert

      • This macro is used by the printErrorAlerts and printInfoAlerts but you can also use it directly to display an error or info message anywhere on the page.

    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:

    • hidden

      • This outputs a hidden input element. Many pieces of the OAuth workflow and the other pages in FusionAuth use hidden form fields to store data. This macro uses the eval feature of FreeMarker in order to pull in data that was in the request. You shouldn’t edit this macro unless you know what you are doing.

    • input

      • This outputs an input element plus a label and any errors that might have occurred on the form field. You can use this for text, passwords, and other input elements. FusionAuth also leverages addons which are icons next to the input field that provide visual cues to the user. This macro allows you to leverage addons as well. Similar to the hidden element, you should not edit this unless you know what you are doing.

    • errors

      • This macro is used by the input macro to render errors on the field. You can use this if you write your own input macros. Otherwise, you likely won’t use this.

    • button

      • This macro renders a button that can be used to submit a form. The FusionAuth version of this macro includes an icon and the button text.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    Subscribe for developer updates