Guide
TrainingSupportCommunity

Modify screen text

Suggest Edits

Modifying Hosted Login Screen Text


As you probably 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 screen that shows up 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:

<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 especially 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 when rendering a page, it looks for the tag name (e.g., 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 translation 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. These tags can be changed by using the Console (below) or by using the Identity Cloud's Configuration APIs. In addition, you can also use those APIs to make multiple changes with a single operation.


Use the Configuration APIs to return translation information

Instead of directly viewing the flow, you can use the /config/{appId}/flows/ {flow}/translations operation to return information about all the translations (JTL tags) found in a flow. For example, this Curl command returns all the translations found in the standard flow:

curl -L -X GET 'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/standard/translations' \
-H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='

The resulting API response includes information about the textResetPasswordSuccessScreenHeading translation:

{
    "key": "e6093a8585a2fd644e952427f18ed8a9",
    "path": "fields.textResetPasswordSuccessScreenHeading.value",
    "values": {
        "en-US": "Password Changed"  
    }      
}

If you know the translation key, you can use a Curl call similar to this to return information for a specific translation:

curl -L -X GET 'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/standard/translations/e6093a8585a2fd644e952427f18ed8a9' \
-H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='

Use Console to modify Hosted Login screen text

If you’re only changing a handful of translations, then the fastest and easiest way to do that is by using the Identity Cloud Console. So how fast and easy is it to change translations by using Console? As you’re about to see, all you have to do is complete the following procedure:

  1. From anywhere within Console, click Registration Builder in the navigation pane:

  2. In Registration Builder, click the Actions icon associated with your Hosted Login flow, and then click Edit:

  3. On the home page for the flow, click Fields:

  4. Locate the name of the field (i.e., the translation) that needs to be changed; for example, to change the screen text Welcome to Gizmo!, locate the textSignInScreenHeading field. Click the Edit icon for that field:

    If you aren’t sure which field name corresponds to which bit of Hosted Login screen text, check the appropriate Hosted Login screen reference page to help you zero in on the field name.

  5. On the Edit Field page, note that the current screen text (in this case, Welcome to Gizmo!) is found in the Value field:

  6. Change the Value of the field and then click Save Changes:

After changing screen text, it’s a good idea to wait a minute or two before accessing Hosted Login and verifying that the changes have taken effect. With that in mind, wait a minute or two, then access your Hosted Login sign-in screen. With any luck, and in our example, the heading Welcome to Gizmo! should now read Identity Cloud Documentation:

You can also use this approach to modify a localized version of a Hosted Login screen. For example, to change the text for the French Canadian (fr-CA) version of your sign-in screen, follow the previous instructions until your arrive at the Edit Field page:

Before you update the text, click the Manage Localized string dropdown and then click the appropriate locale:


📘

Just a reminder that you might not see fr-CA in your dropdown list; instead, you’ll see the locales that have been configured for your flow.


After picking a locale, enter the new Value for your sign-in screen title (in French), and then click Save Changes:

Wait a minute or two, then use the ui_locales parameter to access the French Canadian version of your sign-in screen:


📘

If you want a fully-localized version of the sign-in screen (which you probably do), you’ll need to provide French translations for each piece of text that appears on that screen.


Use the Identity Cloud Configuration API to modify Hosted Login screen text

If you'd rather use APIs to change screen text, that's fine: one simple API call is all it takes to change a piece of Hosted Login screen text. For example, suppose you don’t like the default text Password Changed. In that case, 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 operation and, in the request body, specify the ID of the key to be changed and the new text to be assigned to the en-US locale:

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

📘

You can also use the /config/{appId}/flows/{flow}/locales/{locale}/fields/{field} operation to change a translation value. Likewise, the /string operations can  be used to change these values, meaning that there are plenty of options available to you. However, for this documentation we'll focus exclusively on the /translations operation.


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:


📘

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 Localize screen text 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.


📘

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 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.


Modify multiple translations with a single API call

Both  Console and the /config/{appId}/flows/{flow}/translations operations are excellent choices if you need to change one or two translation values. But what if you want to change 50 translation values, or 100 translation values? Needless to say, manually changing 50 field values in Console or making separate 100 API calls would be both tedious and time-consuming.

To say the least.

Fortunately, however, there’s a way to use the /translations operation to make multiple updates with a single API call. And, in a moment, we’ll show you how to do just that.

First, however, let’s take a quick look at the top half of the Hosted Login sign-in screen. As you can see, there's no shortage of text elements we can change: the screen heading (Welcome to Gizmo!), the screen description (Sign in to reap all the benefits of this fantastic website), even the Sign In label attached to the Sign In button:

So can we really change all these text elements with a single API call? Let’s find out.

To change multiple translations with just one API call, start by creating a spreadsheet containing all the translations you want to modify. For example, this spreadsheet contains the names of five of the translations used on the sign-in screen:

In order to keep this example reasonably simple, we’ve copied the translations names from the sign-in screen text reference. However, you could also use the /config/{appId}/flows/{flow}/translations to return all the translations currently in your Hosted Login flow, and then paste that information into the spreadsheet. If you go that route, you’ll then need to delete all the columns in that spreadsheet except for two: the key column and the en-US column. (For this exercise, we’re changing the US English text.)


📘

Do you have to delete all the translations that you don’t want to modify? That’s up to you. However, if you decide to leave those translations as-is, just make sure that you don’t delete the current value of that translation (e.g., Welcome to Gizmo!). If you do that then, after you make your API call, the value of that translation will be replaced with, well, nothing. In other words, only change the things that needed to be changed. Leave everything else as-is.


If you’re manually adding translations to the spreadsheet you now need to do two things. First, and in column B, enter the new text for each translation. For example:

Second, replace the translation name with the translation key. Key values can be retrieved by calling the /config/{appId}/flows/{flow}/translations API operation:

When you’re done, insert a new row at the beginning of the spreadsheet, entering key in Column A and en-US in column B. Your spreadsheet should look similar to this:

Finally, save your new spreadsheet as a comma-separated values (CSV) file.

Now it’s time to call the PATCH method and the /config/{appId}/flows/{flow}/translations operation. To do this, copy the contents of your CSV file and paste that data into the request body of your API call. For example, if you’re using Postman, your request body will look something like this:

In addition, you need to add the Content-Type header to the API call, and set the value of that header to text/csv. In Postman, that looks like this:

If you’re using Curl (and not using Postman), you API call will look similar to this:

curl -L -X PATCH 'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/textChanges/translations' \
-H 'Content-Type: text/csv' \
-H 'Authorization: Basic 2744Zmc2ZjQ0bXNhYzN2ZXBqanZ40ac5dnQzZTNzazk6O2rt3bhrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpl eb2=' \
--data-raw 'key,en-US
1e59da274168d41a840d66aeccd0ecc8,Identity Cloud Documentation
396cebd8cfcaddcd9cb3d9680887511b,Sign in to access documentation and training information for the Akamai Identity Cloud.
a08db6bdc846bbdc2ba6413dccc8eaad,Sign in by using your email address
9fdf2c17900ac5fc2eb21ddf08f0a22c,Log In
11c5e0a55aeb2a859cabeea11df10bf4,I forgot my password'

At this point, you can make your API call; if everything goes as planned you’ll get back a 204 No Content response and all the translations specified in the API call will be updated (and all the translations not specified in the API call will be left alone). To verify this, you can use the GET method and the /config/{appId}/flows/{flow}/translations operation to see if the translations have been changed. Alternatively (in this case, anyway), you can wait a minute or two and then access your Hosted Login sign-in screen:

Success!

Updated almost 2 years ago