Customize layouts

You can customize the layout and branding of user interfaces like the login page, registration page, username and password recovery pages, and single sign-on pages.

All UIs are available in the following apps located in the <IS_HOME>/repository/deployment/server/webapps folder.

• authenticationendpoint
• accountrecoveryendpoint
• x509certificateauthenticationendpoint

General components of the UI

All pages of WSO2 Identity Server are separated into three general components as shown below. You can reference these components when you form the custom layout.

Layout syntaxes

This section explains the special syntax that you can use to create a custom layout.

• Condition block

  This is similar to an IF block. In the following example, the condition block will activate or deactivate according to the value of the isPolicyPage variable.

  {{#isPolicyPage}}
  <main class="policy-page">
      <div class="ui borderless top fixed app-header menu" id="app-header">
          <div class="ui container">
              <div class="header item product-logo">
                  {{{ProductHeader}}}
              </div>
          </div>
      </div>
      <div class="app-content policy-page-content" style="padding-top: 62px;">
          <div class="ui container">
              {{{MainSection}}}
          </div>
      </div>
  </main>
  {{{ProductFooter}}}
  {{/isPolicyPage}}
  

  • If the value of isPolicyPage is true or any non-empty string, then the content inside the block will be executed.
  • For all other values including null and undefined, the content of the block will not be executed.

• Not Condition Block

  This is similar to an IF block but with a NOT condition.

  {{^isPolicyPage}}
  <div class="page-wrapper layout-file {{#isErrorResponse}}error-page{{/isErrorResponse}}
      {{#isSuccessResponse}}success-page{{/isSuccessResponse}}">
      <main class="center-segment">
          <div class="ui container medium center aligned middle">
              {{{ProductHeader}}}
              {{{MainSection}}}
          </div>
          {{{ProductFooter}}}
      </main>
  </div>
  {{/isPolicyPage}}
  

  • If the value of isPolicyPage is false, an empty string, null or undefined, the content inside the block will be executed.
  • For all other values, the content of the block will not be executed.

• Component Syntax

  This syntax will be used to indicate the position of the general component in the custom layout code. The component syntaxes will be replaced with actual content at runtime.

  {{^isPolicyPage}}
  <div class="page-wrapper layout-file {{#isErrorResponse}}error-page{{/isErrorResponse}}
      {{#isSuccessResponse}}success-page{{/isSuccessResponse}}">
      <main class="center-segment">
          <div class="ui container medium center aligned middle">
              {{{ProductHeader}}}
              {{{MainSection}}}
          </div>
          {{{ProductFooter}}}
      </main>
  </div>
  {{/isPolicyPage}}
  

• Data Syntax

  This syntax can be used to add data to the layout code.

  <script src="{{BASE_URL}}/script.js"></script>
  

  The value stored in the BASE_URL variable will be converted to a string and placed in the corresponding location at runtime. All data syntax values will be sanitized before adding to the layout code.

  Info

  All these variables will be provided by JSP pages. To get more data from JSP pages, add the data into the layoutData map object found in each JSP page.

Add custom layouts

Follow the steps below to customize the layout for login, registration , username and password recovery, and single sign-on pages.

Tip

While authenticationendpoint is used to explain the steps below, the same steps can be carried on for accountrecoveryendpoint and x509certificateauthenticationendpoint.

Note

The <IS_HOME>/repository/deployment/server/webapps/ directory will be referred to as the webapps folder in the following steps.

Step 1: Create the extensions folder

Navigate to webapps/authenticationendpoint and create a new folder named extensions.

Step 2: Create the basic custom layout resources

To create the basic custom layout resources:

1. In the authenticationendpoint folder, navigate to the created extensions folder and create the layouts, custom and carbon.super folders as follows.

   └── extensions
       └── layouts
           └── custom
               └── carbon.super
   

2. Navigate to the webapps/authenticationendpoint/includes/layouts/centered folder, copy the body.html file, and add it to the created carbon.super folder.

3. Create the following files and the folder inside the carbon.super folder:

   • styles.css file
   • script.js file
   • assets folder

Step 3: Add a custom layout design

To add a custom layout to the login page:

1. Navigate to webapps/authenticationendpoint/extensions/layouts/custom/carbon.super/ and follow the instructions provided below:

   1. Copy the code snippet from the html file into the body.html file.

   2. Copy the code snippet from the css file into the styles.css file.

   3. Copy the code snippet from the javascript file file into the script.js file.

   4. Copy the illustration.svg file into the assets folder.

   Note

   To update the header and the footer, use the Branding UI.

2. Clone the identity-apps repository from Github. This directory will be referred to as IDENTITY-APPS-HOME in the next step.

3. Build the source code.

   1. Copy the <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/extensions/layouts/custom directory and place it into the <IDENTITY-APPS-HOME>/identity-apps-core/components/login-portal-layouts/layouts directory.

   2. Navigate to <IDENTITY-APPS-HOME>/identity-apps-core/components/login-portal-layouts directory and build the source code using mvn clean install command (Build should be succeeded for further steps).

   3. Copy <IDENTITY-APPS-HOME>/identity-apps-core/apps/authentication-portal/src/main/webapp/extensions/layouts/custom folder (Compiled version of the layout source code) and paste it into the <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/extensions/layouts directory.

4. Refresh the browser and check out the added custom layout.

   Tip

   If the server stops working after the changes are added, restart the server before verifying the changes.

Best Practices

Use the following best practices when creating a custom layout:

• Add a prefix for the new CSS classes so that the newly added classes will not conflict with existing classes.

• In your development environment, be sure to add the cache="false" flag as a parameter in the <layout:main> tag of all pages that require testing with the custom layout. With this flag in place, the layouts will compile at runtime eliminating the need to manually recompile layouts. Remember to remove this flag in the production environment.