How to Customize User Interface in Apereo CAS

In this article, we are going to see how to customize the user interfaces of a CAS application. 

As you may know already, we are dealing with WAR overlay installation of the CAS project. Within this overlay project, there are no view pages available for us to modify. So first of all, we need to bring down any CAS views which we need to modify into our overlay from the CAS source code.

How to Customize a CAS View

As the first step, on the command prompt, go to the  root folder of your CAS overlay project and give the following command, in order to see all available CAS views:

gradlew listTemplateViews

If you want to bring down the CAS login view to our overlay project, use the following command:

gradlew getResource  –P resourceName= casLoginView.html

Then “casLoginView.html” should be available in “src/main/resources/templates/” folder of your overlay.

If you like, you can unzip the CAS web application and the internal resource jar using the following command:

graldew explodeWar

Now you can manually copy the required HTML file into “src/main/resources/templates/” and then modify it.

Note: After unzipping the resource jar, the “getResource” command may fail with the message “cas-server-webapp-resources-XXX.jar’ does not exist. In that case, all the views may be available “build\cas\WEB-INF\classes\templates” folder.

You can see CAS views consist of smaller fragments which are available in “src/main/resources/templates/fragments” folder. If you need to modify a specific part of the login page for example either header or footer, then you need to modify the relevant fragment available in this folder. You can even add your own fragment in this folder and then modify “casLoginView.html” in the following way:

<div th:if="${headersList}">
   <div class="row">
	<div id="headers" class="headerlist-panel col-12" th:if="${headersList != null}">
		<div th:replace="fragments/headerslist :: headerslist">
		  <a href="fragments/headerslist.html">headers list goes here</a>
		</div>
 	</div>
   </div>
</div>

In the above example “headerList” is a list of items passing from the backend (when the login page is loading). If the “headerList” parameter has a value, then “headerlist.html” fragment will be displayed on the login page. Inside “headerlist.html” fragment, you can have coding to iterate the list and display them.

Note: CAS uses "Thymeleaf" for markup rendering. So to modify CAS view, you must have a bit of the basics of Thymeleaf.

CSS, images, and JavaScript files should be in the “src/main/resources/static/” folder and they should have their own folders respectively “css”, “Images” and “js”. If you want to modify the default “cas.css” file, you can do so by bringing it down and placing that file inside “src/main/resources/static/css” folder. Instead of modifying the above default “cas.css” file, if you want to have your own cutom.css file, then you want to modify the “cas.standard.css.file” property inside the “cas-theme-default.properties” file located inside“src/main/resources/” folder.

All UI messages appearing in the views are available “messages.properties” file inside the resource folder. However, if you want to overwrite those default messages or add some additional messages, CAS recommended way to do so, is placing them in “custom_messages.properties” file which you should place inside “src/main/resources” folder. 

The following is how the folder structure of the “src/main/resources” folder would look like in a CAS overlay project.

Now we have some idea of modifying CAS views and where to place those files inside our project. Next time when we build our overlay project, it will pick up files available (i.e. modification to the views we have done) inside “src/main/resources” folder of the overlay project.  So once it will be up and running, we can see the modification we have done.