Creating Themes for the Customer Console and SQM in Trustwave SPE


This article applies to:

  • Trustwave SPE/MailMarshal SPE 3.6 and above

Question:

  • How can I customize the look of the MailMarshal SPE Customer Console site?
  • How can I customize the look of the MailMarshal SPE Spam Quarantine Management site?

Procedure:

The most basic level of customization for the Customer Console website is setting of your product name and company name, and customized logos for each Reseller and Customer. All of these features are available through the Admin Web Console user interface.

MailMarshal SPE 3.6 and above also provides the ability to download, modify, and upload themes for the Customer Console and SQM through the Admin Web Console.

  • Caution: Most releases include changes in the Customer Console and SQM themes to support new functionality. When upgrading, you will need to create new customized themes based on the default themes.
    • Release 4.0 includes breaking changes to the SQM login page.
    • Release 3.6.2 includes significant changes in the Customer Console themes from 3.6.1.
  • To upload most themes you will need to increase the allowed size of uploads in IIS. See article Q12949.

Controlling Use of Themes:

To enable and disable use of themes, in the Admin Web Console, navigate to Global Configuration > Customer Settings and select the Themes tab.

On this tab you can:

  • Download themes and upload new themes for global use.
  • Enable or disable use and administration of Themes by Resellers.
  • Enable or disable use of unique themes for each Customer.

If Reseller themes are enabled, to enable or disable use of themes for each reseller, in the Admin Web Console edit the Reseller entry.

  • If themes are enabled for a Reseller, they can change themes settings in the Admin Console (Reseller Settings > Themes).

If Customer Themes are enabled, to enable or disable use of themes for each customer, in the Admin Web Console edit the Customer entry and see the Themes tab.

  • If themes are enabled for a Reseller, they can enable or disable customer themes and change themes settings for their customers.

To apply a theme for a Reseller or Customer:

  • Ensure that a unique domain name is entered in the Customer Host field of the Reseller or Customer properties. The theme selected for that Reseller or Customer (on the Themes tab) will be applied when the Customer console or SQM is accessed using the Customer Host domain.
    • For example a reseller could have a Customer Host entry of hostedmail.example.com
  • Remember to create appropriate DNS entries to direct all Customer Host entries to the appropriate web server.

Creating New Themes:

To create a Theme:

  1. In the Admin Web Console, navigate to Global Configuration > Customer Settings and select the Themes tab.
    • If Reseller Themes are enabled globally and for a particular reseller, similar functionality is available on the Themes tab of the Reseller Settings page for logins associated with the Reseller.
    • If Customer Themes are enabled, similar functionality is available on the Themes tab of the Customer Settings page, for Service Provider logins or logins associated with a Customer's Reseller.
  2. Select a theme to use as a model. Download this theme.
  3. Unzip the downloaded file.
    • Note the separate folders included for the customer console and SQM. This folder structure must be included in all theme uploads.
  4. Most UI elements have a specific CSS class defined in a stylesheet file. Basic properties for the Customer Console are found in Master.css
    • Identify the class by using a web development browser plugin, such as Firebug.
    • If you cannot immediately locate the class, search in all the files for the specific class. Once you have located it, modify the file accordingly.
    • You can change or add images in the images subfolder.
    • Theme upload allows a zip file of 20 MB. However an optimized theme should not require more than 2 MB (the default theme file is under 1 MB).
    • Supported file extensions are: "txt", "css", "ico", "png", "gif", "jpeg", "jpe", "jpg"
      Notes:
      • "txt" files are allowed in the theme/zip file to include instructions, copyright or other information to administrators. However, these files will not be extracted, copied to servers, or used in any way, because they can be a security risk in Internet Explorer. 
      • The URL /ImageHandler.ashx?customlogo is used to reference the main logo for the console.
        • If a logo is selected through the "Branding" function of the admin console, that logo will be used. Otherwise, the logo file from the applicable theme will be used (\customerconsole\images\logo.png).
        • You can also replace this URL with a reference to another image.
  5. Some Internet Explorer specific changes are included in ie-style.css. Check your changes in different browsers to ensure you have modified the necessary entries. 
  6. The file print.css defines layout when printing pages. You must retain this file without editing.
  7. When you have completed changes, upload the new theme in Global Configuration, or in the appropriate location for a specific reseller or customer.
    • A theme uploadedto gloabl themes will also be available for selection in the Reseller and Customer themes. A theme uploaded by a Reseller will be available for selection in their Customer themes.
  8. To use the theme, make it the default on the appropriate Themes tab.
    • This could be global, for a reseller, or for a specific customer.
  9. To ensure that themes are applied for a Reseller or Customer, make a unique Customer Host entry in settings for that Reseller or Customer.

 

Upgrade Behavior:

When you upgrade MailMarshal SPE, the default theme will be overwritten. Any additional themes that you have created will not be changed.

  • In most cases, after upgrading you must edit or re-create additional themes to support new functionality.

Notes:

  • On a server with multiple websites, to handle the Customer Host entry the Customer Console site must be bound for * (all unspecified domain names).
    • For instance, if the Admin Console and Customer Console are installed together, you must manually configure this binding.
  • For HTTPS, to handle the Customer Host entry you must install SSL certificates and bind each name to the Customer Console site.
  • If the default theme is damaged, you can restore it by running the Database Wizard on the Admin Web Console server. You can run the Database Wizard without making any changes to database settings.

Last Modified 6/28/2018.
https://support.trustwave.com/kb/KnowledgebaseArticle16189.aspx