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. See Abiquo_UI_Style_Images_and_Colors.pdf

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

• When a user logs in, Abiquo displays the theme for the user's enterprise. If the user's enterprise does not have a theme, Abiquo also uses the default theme. (So if all your enterprises will have the same theme, you can create one theme and set it as the default theme to style both the tenant UI and the login screen).

Copy sample theme files to customize

The platform stores the themes as part of the user interface in the theme folder.  The base theme is called abicloudDefault.

To create themes, copy the sample_theme folder, rename it with the new theme name, and customize the CSS as described in this documentation. The sample CSS is not suitable for use in Abiquo directly. The sample_theme_2 file contains color examples. 

Note that the platform overwrites the abicloudDefault, sample_theme and sample_theme_2 files in every release.

ui/theme/

│   ├── abicloudDefault

│   ├── css
│   │   ├── app.min.css
│   │   ├── theme_guacamole.css
│   │   ├── theme_novnc.css
│   │   └── theme_wmks.css
...
 ├── sample_theme
    │   ├── css
    │   │   └── theme.css
    │   └── img
    │   ├── abiquo_gray.png
    │   ├── abiquo_login.png
    │   ├── abiquo_logo.png
    │   ├── abiquo_watermark.png
    │   ├── favicon.ico
    │   └── mainmenu-buttons.png
    └── sample_theme_2
     ├── css
     │   └── theme.css
     └── img
     ├── abiquo_login.png
     ├── abiquo_watermark.png
     └── mainmenu-buttons.png

The CSS files for branding are described in the following table.

Design a new theme

A new theme may include both image files and CSS.

The image files used by Abiquo in the sample theme can be used as a reference when developing your images. The image files are described in the Sample Theme Image Reference and the color scheme is described in Abiquo_UI_Style_Images_and_Colors.pdf.

As mentioned above, the Abiquo sample_theme contains CSS to modify the theme for enterprise branding and the sample_theme_2 contains examples with other colors.

To get you started, here are some tips for working with CSS.

• Always copy the sample file to a new file and rename it
• Always work with classes because IDs will change from one version to the next
• Cascading Style Sheets are hierarchical, so do not change the order of styles in the file unless you know what you are doing
  
  • At times, changes to CSS may result in unexpected side effects
• If you have never worked with CSS before:
  
  • Start with basic changes to the elements in the style sheets, for example colors.
  • Consider reading about how CSS works and doing some tutorials before you begin advanced branding

Customize main menu buttons

You can replace the icons of the top menu bar with your own icons that are 30x30 pixels in size. You can use an icon sheet or individual images. An icon sheet is the more efficient option. 

Add the icon sheet file to the img directory and use CSS coordinates to reference the location of each icon on the sheet. For an example of the icon sheet, see Sample Theme Image Reference.

Here is an example of the CSS used to reference the virtual datacenter icon in the icon sheet. 

.main-menu-section-link-icon-library {
  background: url(../../abicloudDefault/img/mainmenu-buttons.png) no-repeat 0 -90px;
}

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

The CSS to load the main menu buttons in the same format as the Abiquo icon sheet is as follows. We recommend that you copy the latest version of this CSS from the UI using developer tools in your browser. 

/* 30x30 pixel icons, loaded as background.*/

.main-menu-section-link-icon-home {
   background: url(../img/mainmenu-buttons.png) no-repeat 0 0;
}

.main-menu-section-link-icon-structure {
   background: url(../img/mainmenu-buttons.png) no-repeat 0 -30px;
}

.main-menu-section-link-icon-data {
   background: url(../img/mainmenu-buttons.png) no-repeat 0 -60px;
}

.main-menu-section-link-icon-library {
   background: url(../img/mainmenu-buttons.png) no-repeat 0 -90px;
}

.main-menu-section-link-icon-users{
   background: url(../img/mainmenu-buttons.png) no-repeat 0 -120px;
}

.main-menu-section-link-icon-pricing{
   background: url(../img/mainmenu-buttons.png) no-repeat 0 -150px;
}

.main-menu-section-link-icon-events{
   background: url(../img/mainmenu-buttons.png) no-repeat 0 -180px;
}

.main-menu-section-link-icon-configuration{
   background: url(../img/mainmenu-buttons.png) no-repeat 0 -210px;
}

.main-menu-section-link-icon-home-active {
   background-position: -40px 0px;
}

.main-menu-section-link-icon-structure-active {
   background-position: -40px -30px;
}

.main-menu-section-link-icon-data-active {
   background-position: -40px -60px;
}

.main-menu-section-link-icon-library-active {
   background-position: -40px -90px;
}

.main-menu-section-link-icon-users-active {
   background-position: -40px -120px;
}

.main-menu-section-link-icon-pricing-active {
   background-position: -40px -150px;
}

.main-menu-section-link-icon-events-active {
   background-position: -40px -180px;
}

.main-menu-section-link-icon-configuration-active {
   background-position: -40px -210px;
}

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. 

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

    Click here to expand...

   .main-background-color {
       background-color: #FFFFFF;
   }

2. The default logo displayed in the top-left corner of the screen. If an enterprise doesn't have a logo defined by editing the enterprise, Abiquo will use this one. Search for "abiquo_logo.png" and replace it with your logo name. Then add your logo file in the img directory.

    Click here to expand...

   .main-menu-logo .ab-logo.default-cover {
       background: transparent url("../img/abiquo_logo.png") no-repeat 50% 10px;
   }

3. Change the font color for the main menu buttons. Search for the following CSS and replace the colors for the different link states as required. 

    Click here to expand...

   .main-menu-section-link {
       color: #FFFFFF;
   }
   .main-menu-section-link:visited {
       color: #FFFFFF;
   }
   .main-menu-section-link:hover {
       color: #FFFFFF;
   }
   .main-menu-section-link-active {
       color: #ec9032;
   }
   .main-menu-section-link-active .fa {
       color: #ec9032;
   }
   .main-menu-section-link-active:visited {
       color: #ec9032;
   }
   .main-menu-section-link-active:hover {
       color: #ec9032;
   }

4. Change the font color for the user's enterprise name in the main menu. Search for the following CSS and replace 99999 with a valid web color.

    Click here to expand...

   .main-menu-enterprise-label {
       color: #999999;
   }

5. Change the background color for the header menu. Search for the following CSS and replace the color as you prefer.

    Click here to expand...

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

6. Change the background color for the footer menu from the default of #333333.

   As you can see, the default style uses the same colors for several similar elements and you can perform a search and replace for these multiple elements.

    Click here to expand...

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

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

    Click here to expand...

   .side-menu-font {
       color: #000000;
   }
   .side-menu-font:hover {
       color: #000000;
   }
   .side-menu-font-active {
       color: #FFFFFF;
   }
   .side-menu-font-active:hover {
       color: #FFFFFF;
   }

8. Change the color of the user name at the right of the top menu bar

    Click here to expand...

   .main-menu-user-name-link {
       color: #ec9032;
   }

9. Change the color of the popup header bar

    Click here to expand...

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

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, edit the client.themes UI property in the /var/www/html/ui/conf/client-config-custom.json file accordingly.
   Add the themes in the order they will appear in the Edit enterprise popup. The abicloudDefault theme must be the first on the list, or the Abiquo UI will not run.
   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. In Users view, edit the enterprise

   1. Enter the Enterprise logo with the relative path from the folder where it is located, e.g. theme/blue_theme/img/abiquo_gray.png

   2. Select the enterprise theme from the Default theme pull-down menu.
   

Use the style sheet reference document to develop advanced branding

After you have tried some basic changes, the Abiquo style sheet PDF can help you to visualize the CSS elements that you need to change to achieve a specific look. 

Reference document for Abiquo branding: 

• Abiquo_UI_Style_Images_and_Colors.pdf
• Abiquo_UI_Style_Sheet_v40.pdf

Remember that you can also use your browser's web developer tools to identify CSS elements.

Set a default theme for login and enterprises without themes

To style the login zone, set a default theme. The platform will also use this theme for any enterprises without their own themes. So if all your tenants will have the same theme, you can create enterprise branding in this theme too and set it as the default.

• When you set a default theme, Abiquo still requires the abicloudDefault theme
• You do not need to add the default theme to the list of themes in client-config-custom.json unless it should appear on the Edit user dialog as a selectable 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

• If you do not wish to use a symbolic link 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.

Assign branding privileges

If the administrators managing tenants are not cloud administrators, remember to assign branding privileges in Abiquo.

In Users View, check that the users have the "Manage enterprises" and "Modify enterprise theme" privileges. See Manage Roles

Users clear browser cache to display new themes

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.