Customise DHIS 2 login screen

This article is designed to show the tools/methods that can be used to modify a DHIS 2 log in screen. The first two sections will discuss the two main methods: gui and css. The third part will briefly look at how to deal with more complex requirements.

GUI

When working on a custom log in page, the first place to go to is the system settings application. In system settings it is possible to make quite a number of changes to the login without having to delve into more complex css and curl commands. Depending on the requirement, it could be possible to make all the required modifications here. Below is an outline of some steps.

  • From the applications menu, navigate to the System Settings app.

  • Choose 'Appearance' from the Left side menu.

  • Complete / modify relevant fields in the system settings screen

    • Most commonly useful fields include:
      • Application title and introduction
      • Application notification
      • Flag - You are restricted to the options available in the drop down. If you really need a different flag to the ones available, you'll need to submit a Jira request. In your Jira request you should attach an image containing the new flag. The image needs to be 160px wide. * Custom login page logo - this is the image that appears above the login field. Here you can click 'REPLACE IMAGE' to upload any .png image. It is useful to make sure your image is a sensible size before uploading.
      • Check that you see a 'Settings updated' message pop up at the bottom of the screen. You may need to update cache to see the changes.

The changes made above have transformed the login from this...

To this...     

In some cases the system may require the user to consent to some terms before logging in. This can be done by adding a small script to the system default application introduction field:

  1. First go to the system settings app
  2. Next select the appearance section from the left hand menu
  3. Find the ‘Application notification - English’ field
  4. Scroll down and click 'Set the main field value before adding a translation' text. This will allow you to set the system default value rather than a language specific value.
  5. Below is a sample of what you can paste at the end of the this field to add the consent overlay:
Login overlay
<script>if (!$('.touOverlay').length) { $('body.loginPage').append($('<div class="touOverlay" style="width:100%; height:100%; position:absolute; top:0; left:0; background:rgba(100,100,100,.9); z-index:40000; display: flex;justify-content: center;">' + '<div id="termsOfUsage" style="background:#555; height: 160px;z-index:50000; margin-top: 20em; padding:2em 3em; text-align: center; border-radius: 8px;">' + '<p>This system is not for public consumption or external use without permissions</p>' + '<button onclick="$(this).closest(\'.touOverlay\').remove()">I Agree</button>' + '</div>' + '</div>')) }</script>

As soon as you click away from this field the value will be saved.

Posting CSS

Often requests to update the style involve the need to 'change the background colour' or 'remove the flag' or 'remove that application title text completely'. These are more difficult to do, and cannot be done in the user interface. For these types of requests, we use cascading style sheets (or css).

  • The first step is to identify the elements of the login page that you need to update. To do this, navigate in your web browser to the login page and right click to inspect. Here we will identify the tags we're going to target in our css file.

  • Look at the HTML elements.

    • Handy tip 1: Hovering over an html element in the 'Elements' tab will highlight the parts of the webpage the element points to...

  • Handy tip 2: You can use the arrows to drill down into the html. This can help when you need to find a more specific element (like an image nested in the banner area of the login field)
  • Locate the classes or ids you will need to make the required changes
    • For the background colour of the whole page, you'll want to target the class "loginPage"
    • To remove the login page image completely you could target the href attribute "a" under the "bannerArea" id
    • To remove the flag, target the "flagArea" id
  • Once you have your tags, you can create your css file. I use TextWrangler but I'm sure any text editor would work. To target classes, you need to use a '.' before the class identifier, to target an id use a '#'

  • Save your css file, making sure to use the file extension '.css'
  • To post your css file use a curl command with the following syntax...

Curl syntax

curl --data-binary @filename.css "https://play.dhis2.org/2.31.5/api/files/style" -H "Content-Type:text/css" -u admin:district -v

  • A positive response looks like this:

{"httpStatus":"OK","httpStatusCode":200,"status":"OK","message":"Custom style created"}

  • Check in browser to see the css update has been implemented. You may want to clear your cache and use incognito mode.
  • Below is an image of the changes made by the example css

Existing CSS

Often a server will already have some custom style implemented. We don't want to overwrite that or have to guess how previous developers implemented the login. To see what style has already been applied to a server, navigate to the ".../api/files/style" end point.

It is good practice to copy the output from here and paste it into your css file and make the edits to this. This way your work is modifying or adding to the existing css rather than completely wiping over what was done before.

N.B. To expand the width of the notification area below the login space this can be added to the css file: margin-left: -77px; margin-right: -122px;

Related articles

Content by label

There is no content with the specified labels