Abiquo 5.0

Skip to end of metadata
Go to start of metadata

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

Tip

To configure more than one theme with different URLs for each theme, see Abiquo UI theme per subdomain


 Click here to expand...





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 ...



 Click here to expand...

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

File

Branding for

theme.cssAbiquo UI
theme_guacamole.css

Guacamole remote access console. See Branding Guacamole

theme_wmks.cssWMKS remote console. See Branding WMKS
theme_novnc.cssDeprecated file




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.


 Click here to expand...

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

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


 Click here to expand...

Login logo CSS

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


Login background CSS

.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.