When a user is registering, the last thing you want to do is get in their way or confuse them. In this tutorial, you’ll improve an advanced registration form’s display by modifying a theme.
Previously, we built a self service registration form for a real estate webapp and used FusionAuth as the auth server. It was a two step form which captured information about their home buying needs. However, the form had a few rough elements. In particular, it wasn’t clear which data someone was supposed to enter into which form field.
This tutorial builds on the previous one and walks through changing the theme. While this tutorial will reference the previous form, feel free to apply it to any form you’ve created as well.
This is part of a three part series. Here are all the posts:
- How to use FusionAuth’s advanced registration forms
- How to theme FusionAuth’s advanced registration forms (this one)
- Building a user profile portal with Flask, OAuth, and APIs
Go to “Settings” and then create an API key by going to “API Keys”. We’ll be using this key to script some of our theme management, which means we need permission for this endpoint:
You may also check no endpoints or methods. This creates a super-user key, able to do anything. Well, at least able to access all of the FusionAuth API. This is fine for a tutorial, but for production, please limit access.
Creating a custom theme for a single or multi-tenant configuration
The next step is to create a new theme. You will be changing some of the messages to improve the user experience, and the default theme is read-only. Themes are assigned on a tenant by tenant basis, so you can either change the theme for the default tenant (what this tutorial does) or create a new tenant and assign a new theme to it. FusionAuth supports multiple tenants out of the box, so either way works.
This is the theme you’ll modify throughout the rest of this blog post.
Navigate to “Customizations” and then “Themes”. Duplicate the existing “FusionAuth” theme. Rename your theme to something meaningful, such as “Real Estate Application”. Before you save it by clicking the blue icon, it should look like this:
Navigate to “Tenants” and then edit the “Default” tenant. Go to the “General” tab and update the “Login theme” setting to the new theme. Save the configuration when the screen looks like:
Customizing our theme
Customizing the theme gives you full control over what the user sees. As a reminder, here’s what the first step of the registration flow looked like at the end of the form creation post:
We’re going to add in understandable placeholders and labels, but there’s a lot more you can do; check out the theming documentation for more.
To begin, in the administrative user interface, navigate to “Customizations” and then “Themes”. Find the theme you created above and copy its id; mine is
Modifying a theme via API
To change the hints and validation messages, you must edit a file containing messages. This is a Java properties file, and can be changed via the administrative user interface or the API. In this post, you’re going to use the API to make the changes. This will show the power of the API first approach that FusionAuth takes, as well as providing a way to version control the file, should you so desire.
These scripts assume you are running FusionAuth at
http://localhost:9011; if not, adjust accordingly. These scripts are also available on GitHub. They also require you to have jq and python3 installed locally.
Retrieving a theme file for local editing
First, retrieve the messages. You want them in a text file for easy editing. Below is a shell script which converts the JSON into a newline delimited file:
convert.py script turns embedded newlines into real ones:
While this script only works for the messages file, it can be tweaked to handle other parts of a theme, such as the HTML template files. This is left as an exercise for the reader; pull requests are welcome.
Modifying the messages file
Add your API key and theme ID, then run the script. You’ll end up with a
defaultmessages.txt file in the current directory:
It’s about 200 lines; the above is an excerpt. Open it in your favorite text editor.
If you are interested in localized messages, check out the
To improve the registration form, add values to the “Custom Registration” section. Maintaining sections in this property file isn’t enforced (it’s not a
.ini file) but it's a good idea to change only what is needed. Upgrades to FusionAuth may change the properties file and you will have to merge the changes, so simpler is better. Here is the section to which you're going to add lines:
The keys of the messages file match the field keys for the registration form. Here’s what you’d add to set up placeholders for the real estate application registration form:
You aren’t limited to placeholders, either. You can add validation messages to the section starting with:
# Custom Registration form validation errors. You can examine the
Default validation errors section for examples of all the errors available.
Append the key to provide specific errors for a given form field. For example, to display a user friendly error message when price range information is omitted, add these properties:
If any of the values you add to
defaultmessages.txt have a double quote in them, escape it:
\". This prevents issues when this file is converted back into JSON, which must happen before the changes are reflected in FusionAuth.
Updating the theme in FusionAuth
After you’ve made all your changes to
defaultmessages.txt, you need to turn it back into the JSON format the API expects. You must also add the keys and quotes previously stripped off. Finally, you have to make the update request to FusionAuth. For the update, use the
PATCH method, which only updates the elements of an object provided.
This script performs all the above actions on the
Run this script with the modified
defaultMessages.txt file. This will apply the changes to your theme.
To view the changes, find the registration URL by going to the “Application” tab in the FusionAuth administrative user interface. View your application and copy the registration URL:
Open an incognito window and visit this URL. You should see your shiny new placeholders on the first page:
If you fill out the first step, you’ll see the second page with the correct hints as well:
Validation and theming
On the second screen, if you submit the registration form without providing a price range, you’re shown the error messages added above:
Adding form labels
You can customize your field display more extensively by modifying the
customField macro. This is in the "Helpers" section of your theme. Rather than use the API to do this, let's edit it directly in the administrative user interface.
Navigate to “Themes” and edit your theme. Click on “Helpers” and scroll to the bottom. You’ll be modifying the
customField macro. Here's the default implementation for this FreeMarker macro:
It looks a little wonky if you aren’t used to it, but this is a series of if/then statements which get executed against every custom field as the user interface is being generated. The macro looks at each field definition and creates the correct HTML element. Well, technically, it calls another macro such as
select, but you get what I mean. For instance, a
password field will be rendered as an HTML input field with the type
Let’s add a label to each field. Right after
[#assign fieldId = field.key?replace(".", "_") /], add this:
Open an incognito window and go through the registration flow again. You should see labels for both steps. These label values will be pulled from your message bundles, so can be localized in the same way as any of the other messages. As a bonus, because you used the
label HTML element, you can now click on the text label and the browser will put the cursor into the text input field. User experience win!
If you complete the first step, you can see labels are present on the second step as well:
Previewing a theme
It is generally a good idea to review a theme in an incognito window because this will give a feel for the user registration experience. However, at times, you may need to make changes in your theme that you want to view without going through an entire registration process. You can easily do so by previewing the theme.
Navigate to “Customizations” then to “Themes”. Choose your theme, then click the preview link (the green magnifying glass):
Doing this will open a new tab. Click “OAuth register” in the left hand navigation and you’ll see the theme as it would be rendered. You can even switch between steps. Below is the preview for the second step:
If you are using FusionAuth registration forms, be sure to customize the default templates to improve users’ experience. FusionAuth’s themes can be manipulated both in the administrative user interface and by API calls.
But what about after the registration? This information is available via the FusionAuth APIs, in the
registration.data fields. It is also available for viewing, but not editing, in the administrative user interface.
Let’s build a small portal page for the user to see their data. You can retrieve and modify user data using the APIs and in a future blog post we’ll see exactly how to do that.
Originally published at https://fusionauth.io.