Prerequisite: You must be familiar with the Syntax used in Tutorials and have already created an extension.

Starting with version 2.7.0, it is now much easier to customize the login screens of iTop.

The login screens are:

• Login form
• Logoff form
• Change password form
• Reset Password form
• Forgot password form

In this tutorial we will see:

• What is needed to customize the login screens
• How to customize the CSS
• How to customize the HTML

• The first step to customize the login screens is to create an extension.
• Add a class to this extension implementing iLoginUIExtension

class CustomLoginExtension

class CustomCSSLoginExtension implements iLoginUIExtension
{
        public function ListSupportedLoginModes()
        {
                return array('form');
        }
 
        public function GetTwigContext()
        {
                return null;
        }
}

Use ListSupportedLoginModes() to specify that your login extension will be called on form authentication.

The method GetTwigContext() will be used to indicate the parts of the login screens you want to customize.

If you want to add a new CSS for the login screens, you can:

• Provide a CSS file in your extension (in our case it will be under css/custom.css)
• Create a context to indicate where the CSS file is located

class CustomLoginExtension

class CustomCSSLoginExtension implements iLoginUIExtension
{
  public function ListSupportedLoginModes()
  {
    return null;
  }
 
  public function GetTwigContext()
  {
    $oLoginContext = new LoginTwigContext();
    $oLoginContext->AddCSSFile(utils::GetAbsoluteUrlModulesRoot().'<your-module>/css/custom.css');
    return $oLoginContext;
  }
}

Use the method AddCSSFile() of the class LoginTwigContext to declare all the CSS files you want to provide. The parameter is the URL of the CSS file.

Use the iTop file css/login.css as an example to know the ids and classes used in the login screens.

The common ids used in every login screens are:

The login screens use Twig to generate the HTML. If you are not familiar with Twig, here is the documentation. The templates are located in templates/login.

All the login screens extends the same template:

You can overwrite existing login templates by providing a file with the same name in your extension.

For example if you want to redefine the template base.html.twig, you can provide the file base.html.twig. Within this file you can refer to the standard template provided by iTop by starting your file with:

base.html.twig

{% extends '@ItopCore/base.html.twig' %}

now you can redefine any block defined in base.html.twig and even refer to the standard implementation of this block like this:

base.html.twig

{% extends '@ItopCore/base.html.twig' %}
 
{% block login_content_outer %}
<div id="login-content-container">
        {{ parent() }}
</div>
{% endblock login_content_outer %}

Here the notation {{ parent() }} refers to the content of the parent template.

The login screen (login.html.twig) provides a way to add HTML to the current screen.

You can define additional content in a Twig template and insert it at various places in the screen. The following blocks can be extended:

In order to extend one block, you have to provide a template like this (the example is taken from datamodels/2.x/authent-cas):

cas_sso_button.html.twig

<div class="sso-button" title="{{ aData.sTooltip }}" onclick="$('#login_mode').val('{{ aData.sLoginMode }}'); $('#login_form').submit(); return false;">
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 336.82 167.83" class="logo sso-image" style="max-height: 20px;">
    ...
  </svg>
  {{ aData.sLabel }}
</div>

Then you have to indicate which block to extend in the login screen:

CASLoginExtension.php

  public function GetTwigContext()
  {
    // Create the context
    $oLoginContext = new LoginTwigContext();
    // Indicate that templates are in view directory
    $oLoginContext->SetLoaderPath(utils::GetAbsoluteModulePath('authent-cas').'view');
 
    // Prepare some variables for the template
    $aData = array(
      'sLoginMode' => 'cas',
      'sLabel' => Dict::S('CAS:Login:SignIn'),
      'sTooltip' => Dict::S('CAS:Login:SignInTooltip'),
    );
    // Create an extension block for the template cas_sso_button.html.twig
    $oBlockExtension = new LoginBlockExtension('cas_sso_button.html.twig', $aData);
    // Attach the extension to the block named 'login_sso_buttons'
    $oLoginContext->AddBlockExtension('login_sso_buttons', $oBlockExtension);
 
    return $oLoginContext;
  }

When you create an extension block, you can provide variables computed in PHP. The variables are passed to the template in the array named aData.