Abiquo Branding Guide

Changes to branding

See Changes to branding

Introduction to Branding

The Abiquo HTML 5 user interface can be branded for the login screen and at the tenant level with multiple different themes. 

• The login screen uses the default theme

  • To customize the login screen, create a theme that styles the login elements and set it is as the default

• When a user logs in, Abiquo displays the user's enterprise theme as defined in the UI
  • If the user's enterprise does not have a theme, Abiquo also uses the default theme
    
    

Branding CSS files and folders

This directory listing contains the CSS files for the default theme, which include the files for remote access

ui/theme/

│   ├── abicloudDefault

│   ├── css
│   │   ├── app.min.css
│   │   ├── theme_guacamole.css
│   │   ├── theme_novnc.css
│   │   └── theme_wmks.css
...
 ├── sample_theme
    │   ├── css
    │   │   └── theme.css
    │   └── img
    │       └── menu-sprite.png
... 

Copy sample theme files to customize

The platform stores the themes in the user interface files in the theme folder. 

• Base theme: abicloudDefault
• Sample theme: sample_theme

The sample theme CSS is not suitable for use in Abiquo directly. 

The platform overwrites the default and sample theme folders at every release.

To create a theme:

1. Copy the sample_theme folder
2. Rename the folder with the new theme name that will display for the administrator in the Abiquo UI 
3. Optionally copy the CSS files for remote access to the new theme's css folder
   1. theme_guacamole.css 
   2. theme_wmks.css

Design a new theme

Your new theme may include both image files and CSS.

• The basic UI images and colours are described in this PDF file Abiquo_UI_ Style_Images_and_Colors_ v5.0.0.pdf
• The basic UI image files are also described in the Sample Theme Image Reference.
• You can copy the abicloudDefault img folder from your Abiquo Server to obtain all the default images
• You can style the UI using CSS from the sample_theme

Customize main menu buttons

The platform loads the images on the main menu buttons from the Abiquo icon sheet. For full details, see the Sample Theme Image Reference.

To customize the main menu buttons, you can use an icon sheet or individual images:

1. Add the icon sheet file or image files of 24 x 24 pixels to the img folder in your theme 
2. Use CSS

   1. to reference the location of each icon on the sheet, for example

      This means that the top left-hand corner of the icon is at the coordinates (0,-144).

      .main-menu-section-link-icon-data {
                                          background-image: url(../img/menu-sprite.png);
                                          background-position: 0 -144;
      }

   2. or to load an individual icon from its own image file

      To load the whole image, you must use background-position of 0 0. 

      .main-menu-section-link-icon-data {
                                          background-image: url(../img/MY_VDC_IMAGE.png);
                                          background-position: 0 0;
      }

We recommend that you copy the latest version of this CSS from the UI using developer tools in your browser. 

Set a default logo for all enterprises

To set the default logo for all enterprises:

1. The space reserved for the logo file is 48 x 48 pixels. See Sample Theme Image Reference

2. Add your logo file to the your main theme's img directory

3. In Abiquo, go to Configuration view → General
4. For the Default logo, enter the relative address of your logo file

Branding CSS examples

Here are some branding examples to help you get started. When you copy the sample_theme folder to a new folder, make a note of the folder name because it is the name of the theme and you will need to configure and select it in Abiquo later.

Edit your theme.css file and modify the following elements to style the UI for the enterprise. 

The following examples may differ from the sample files. The sample files will be updated whenever necessary but these examples will only be updated occasionally.

1. Change the background color of the application. Search for the CSS class ".main-background-color" and change FFFFFF to another valid web color, for example, light grey EEEEEE

2. Change the background color for the main menu. Search for the following CSS and replace the color as you prefer.

    Click here to expand...

   .main-menu {
       background-color: #333333;
   }

3. Change the font color for the left side list by searching for and replacing the following colors

    Click here to expand...

   .main-menu .centering-container-menu li .main-menu-section-link-active small,
   .main-menu .centering-container-menu li.main-menu-section-link-active a span {
       color: #COLOR_HEX;
   }

4. Change the color of the primary font

    Click here to expand...

   body {
       color: #ec9032;
   }

5. Change the color of the primary button

    Click here to expand...

   .btn-primary {
       background-color: #719e19;
       border-color: #719e19;
   }

6. Change the color of the popup header bar

    Click here to expand...

   .modal-header {
       background-color: #efa253;
   }

7. Optionally change the background color of the toast error messages

    Click here to expand...

   .toast-success {
     background-color: #51A351;
   }
   .toast-error {
     background-color: #BD362F;
   }
   .toast-info {
     background-color: #2F96B4;
   }
   .toast-warning {
     background-color: #F89406;
   }

Define custom images on the login page using CSS

To set custom images on the login page:

1. Add your files to the theme img folder
2. In the sample-theme.css file, search for the login-logo and login-form_info .card elements
3. For each background-image url, add the relative path of the image file 
4. For the login background, you can also specify the aspect ratio, or style the image further

.login-title {
    background-image: url(../img/MY_LOGO.png); 
    background-size: contain;
}

.login-form_info .card {
   background-image: url(../img/MY_LOGIN_BACKGROUND.png);
   background-size: cover;
   background-position: 50% 50%;
}

Deploy an enterprise theme in the Abiquo UI

To deploy an enterprise theme in the Abiquo UI, do the following steps. (Note that you can find more detailed instructions in the Abiquo Branding Admin Guide)

1. Copy the new theme's folder to the /var/www/html/ui/theme folder on the server where the UI is running. 

   • Make sure Apache is able to access all the theme files. 

2. To enable this theme to be selected for enterprises:

   1. Edit the /var/www/html/ui/conf/client-config-custom.json file 

   2. Go to the client.themes UI property. The abicloudDefault theme must be the first on the list, or the Abiquo UI will not run.

   3. Add your themes in the order they will appear in the Edit enterprise popup. 
      For example, here we have added abicloudDefault, then blue_theme and green_theme:

      
      

      "client.themes" : [
          "abicloudDefault",
          "blue_theme",
          "green_theme"
      ]

      To ensure the new UI properties are properly loaded, log out from the UI, clear your browser cache and log in to Abiquo again

3. Go to Users view → create or edit the enterprise

   1. For the Enterprise logo, enter the relative path from the UI folder, e.g. theme/blue_theme/img/abiquo_gray.png

   2. Select the enterprise's theme from the Default theme list.
      

Develop advanced branding

Use your browser's web developer tools to identify HTML elements and CSS styles and customize them as required.

Set a default theme for login and enterprises without themes

To style the login zone use a default theme. The platform will also use this theme for any enterprises without their own themes. 

• When you set a default theme, Abiquo uses it instead of the abicloudDefault theme
• On the Edit user dialog, to select the default them, select the abicloudDefault theme

To set a default theme, which will persist after upgrades, do one of the following steps:

• In the theme folder, create a symbolic link, named 'default', which points to the desired theme to mark it as the default:

  > theme/ ln -s sample_theme_2 default

  
  Note that Tomcat does not allow access to symbolic links by default and you will need to enable the allowLinking property.
  See https://tomcat.apache.org/tomcat-8.0-doc/config/resources.html#Common_Attributes

• Or if you do not wish to use a symbolic link (e.g. for security reasons), in the theme folder, rename or copy the folder of the theme you would like to use as the default to create a "default" folder.

Remember to check the file ownership and access settings because the Abiquo Tomcat server will need to access the branding files.

Troubleshooting branding

If you have an issue with branding, remember to check your CSS, JSON, and file system access for the branding files.

• Administrator cannot access branding in the UI
  If the administrators managing tenants are not cloud administrators, assign branding privileges to the users in Abiquo. The branding privileges are "Manage enterprises" and "Modify enterprise theme". See Manage Roles

• New themes do not display property

  You MUST clear your browser cache to correctly display a new theme

  
  All users who have previously accessed the platform should clear the browser cache on their machines before logging in to Abiquo again.To test a new logo and theme, log in again as a user of the enterprise you are branding.