How to Modify the Text of Your Hosted Login Screens

As you probably already know, Hosted Login makes it easy to modify the appearance of the screens used for registration, login, and user profile management. For example, consider the following screen, the one that appears after a user has successfully changed his or her password:

What’s wrong with that screen? Nothing; it’s just another Hosted Login screen.

Having said that, however, we understand that you might not want just another Hosted Login screen; instead, you might want to add your own special touches to the Password Changed screen. And that’s fine: using custom CSS (Cascading Style Sheets), it’s easy to change the way your screens look. Would you rather have Password Changed in big red letters, and have that title and the “Your password has been successfully changed” message displayed on a light blue background? No problem:

Furthermore, the ability to make changes to your screens doesn’t just apply to “little” things, either. For example, and depending on how skilled you are at using CSS, you can turn a Hosted Login screen from this:

To this:

And with surprisingly little effort.

But CSS only lets you modify what your screens look like; CSS doesn’t let you change what those screens actually say. For example, let’s take another look at the Password Changed screen:

Again, there’s nothing wrong with that screen, provided that you like the title Password Changed and the message Your password has been successfully changed. But maybe you don’t like those default values, maybe you’d prefer a Password Changed screen that reads more like this:

Will CSS help you here? To be honest, no, it won’t.

But don’t despair: although CSS can’t help you,  there is a way that to change the text on your Hosted Login screens. As it turns out, all the text on those screens is defined by JTL (Janrain Templating Language) tags. For example, the HTML markup for the Password Changed screen looks like this, with the JTL tags highlighted in red:

<div style="display:none;" id="resetPasswordSuccess" class="screen">
  <div class="auth-screen content-wrapper">
    <h1 class="screen-heading">{* textResetPasswordSuccessScreenHeading *}</h1>
    <p class="screen-description">{* textResetPasswordSuccess *}</p>
  </div>
  <div class="footer-container">
    <div class="content-wrapper">
        <span class="help-link">{* textNeedHelp *}{* linkHelp *}</span>
        <div class="footer-text">
        {* textFooter *}
        </div>
        <div class="footer-extra-text">
        {* textFooterExtra *}
        </div>
    </div>
</div>
</div>

As you can see, the words Password Changed don’t appear anywhere in the HTML for the Password Changed screen. Instead, the screen title is denoted by using the following JTL tag:

{* textResetPasswordSuccessScreenHeading *}

So does that matter to you? It might. After all, each JTL tag (minus the curly braces and the asterisks) is defined as a translation within your Hosted Login flow. For example, suppose you search your Hosted Login flow for textResetPasswordSuccess (the JTL tag minus the curly braces and the asterisks). If you do that, you’ll find a file definition similar to this:

That might not look very helpful, but try this: copy the value property (e6093a8585a2fd644e952427f18ed8a9) and search the flow for that. When you do that, you’ll find the phrase Password Changed:

It’s a little bit complicated, but here’s how text ends up on a Hosted Login screen:

  1. Your HTML markup uses a JTL tag any time a text element (heading, a paragraph, the label attached to a button, etc.) needs to be rendered onscreen. Like we said, you won’t see the words Password Changed in your HTML; instead, you’ll see the JTL tag {* textResetPasswordSuccessScreenHeading *}.
     
  2. When the server sees a JTL tag at the time the page is rendered, it looks for the tag name (textResetPasdswordSuccessScreenHeading) in the flow (the flow will always include a field with the same name as the tag name).
     
  3. One of the properties of the field is the value; the value indicates the ID of the translation key associated with the field. The server looks up the associated translation key.
     
  4. The server grabs the text associated with the translation key (e.g., Password Changed) and, when rendering the page, replaces the JTL with the translation key text. That’s how a JTL tag like {* textResetPasswordSuccessScreenHeading *} ends up being displayed onscreen as Password Changed.

Here’s a somewhat more graphical way of looking at things:

So why does that matter to you? Here’s why. Because JTL tags are defined in the flow, that means that you can use the Identity Cloud Configuration APIs to change the value associated with those tags. And by changing the value of the tags you also change the value of the text shown onscreen.

For example, suppose you don’t like the default text Password Changed. That’s fine; just use the Configuration API and the PATCH method to change the text associated with the relevant translation key to something you like better:

curl -X PATCH 'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/translations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U=' \
--d '[
    {
          "key": " e6093a8585a2fd644e952427f18ed8a9 ",
          "values": {
               "en-US": "You Have a New Password Now"     }
     }
]'

As you can see, there’s not a whole lot to the API call. You use the /config/{appId}/flows/{flow}/translations endpoint and, in the body parameter, specify the ID of the key to be changed and the new text value to be assigned to the en-US locale:

[
    {
          "key": " e6093a8585a2fd644e952427f18ed8a9 ",
          "values": {
               "en-US": "You Have a New Password Now"     }
     }
]

And what will your screen look like after your run the preceding API call (as well as a second call that changes the message beneath the heading)? Your screen is going to look a lot like this:

Note. We specified the en-US locale because that’s a locale everyone has, and that’s the locale Hosted Login uses by default. But you can change the text values for other locales; see the article How to Localize the Text of Your Hosted Login Screens for more information.

To change any of the other text elements on this screen just look up the JTL tag, find the associated field, find the associated translation key, and use the Configuration API to change the text assigned to that key. The process is surprisingly easy.

Note. One thing to keep in mind is that some of these text elements, including footer text like Need help? and Visit our help center are used on multiple pages. Because of that, you can’t change the footer text just on the Password Changed screen. Instead, changing the footer text will change that text on all your Hosted Login screens.

To be honest, the hardest part of changing onscreen text isn’t changing the value of the JTL tag; it’s knowing which JTL you need to update. Fortunately, we’ve included a complete guide to the Hosted Login screens, a guide that includes information on every piece of UI text as well as the JTL tag that corresponds to that text. That should make it easier for you to figure out which field (and, by extension, which translation key) needs to be updated.