Web UI Templates Theming

WARNING

When you customize your MailCleaner interfaces or reports, it's your responsibility to maintain your template. When you have differences between our default template (in which we deploy bug fix, new features etc.) and your new one, you have to reconcile our changes with yours manually. You can make note of any changes made within the default theme directories in the Git history and apply changes as necessary.

Introduction

The web user interface is based on template files and thus can be customized to a significant degree, as long as all of the necessary variables and substitution strings remain intact.

Please make sure that you leave all MailCleaner © Copyrights intact and continue to provide upstream links to our license and source code in order to remain compliant with the license requirements.

Creating your own template directories

Templates for the web user interface are located in the folder /usr/mailcleaner/www/user/htdocs/templates and templates for system emails (eg. the summary reports) are in /usr/mailcleaner/templates.

The best way to create your own set of templates is to copy all of the files from the default template as symlinks to your new template, then only replace the files you want to customize. This way, all of the other files will automatically update whenever changes to the default theme are made.

The directory name you select will be the one that is displayed in the drop-down selection so make sure that it is meaningful to you and your users and do not included any spaces or special characters. eg.

cp -Rs /usr/mailcleaner/www/user/htdocs/templates/default /usr/mailcleaner/www/user/htdocs/templates/yourcompanyname

Applying changes to your template directory

Now you can edit the existing files. First, you must selectively delete the symlink for whichever file you would like to modify:

rm /usr/mailcleaner/www/user/htdocs/templates/default/images/login_header.png

In the case of an image, you can create on from scratch with the recommendations below. In the case of a text file, you can start with an actual copy of the file:

cp /usr/mailcleaner/www/user/htdocs/templates/default/css/main.css /usr/mailcleaner/www/user/htdocs/templates/yourcompanyname/css/main.css

and make modifications to that file as necessary.

The files in the default template that are most likely to change over time are those which are necessary for functional changes, primarily the .tmpl files in the root of that template directory. Try not to changes these, if possible. If you do, you must watch for changes to them in the default template so that your users obtain the new features also. We will endeavor to announce significant changes which would require modifications to custom templates as they happen.

Image recommendations

The primary image files that you might want to replace are:

Filename            Size      Purpose
login_header.png    530x75    Login Prompt image
logo_name.png       75 high   Header logo (left)
banner_letters.png  75 high   Header image (right)
header_bg.png       75 high   Header background, repeated

Apply your custom template

To activate your templates, you need to modify Configuration->Domains->[select domain]->Templates->Web user GUI which should now have your new template listed.

The default template to use for quarantine summaries as set in Configuration->Domains->[select domain]->Preferences.

Note: The user login page will use the template configured for the [Configuration->General settings->Defaults->Default domain](https://github.com/MailCleaner/MailCleaner-Next/wiki/Administrator-Interface#Defaults], since the user's domain is not yet known by the time they arrive at the login page.

Also note: System emails have different contents per language. If the template does not exist for the selected language, that user will fallback to the default template in their language. If you have users who are using other languages, you should ensure that you apply your changes (eg. new images) to each language directory.