Theming

In addition to the standard Light / Dark Mode themes available in ProVision, several methods are available to customize the entire product, allowing for additional company branding and fine control over what areas of the product are visible and what are not.

Theming Customization includes:

  • Changing the instance logo and brand name
  • Customizing the visible tabs or subtabs instance-wide
  • Creation of fully custom themes to match company branding

Note: Theming customization requires read/write access on the instance's "assets" directory, and experience using vi or another text editor of your choice to edit options.

Creating a custom theme requires strong CSS knowledge, as well as access and write permissions to your instance's "assets" directory

Table of Contents


Theming Overview

GUI themes can be set on a per-user level, including the much-requested "dark mode" to help alleviate eyestrain.  

In addition, we provide several methods of customizing the entire product, which will allow for additional company branding and fine control over what areas of the product are visible and what are not.

Sub-features included under Theming include:

  • Customizing the instance logo and name
  • Custom Navigation Menu Tab Visibility
  • Standard Dark / Light Mode Themes
  • Custom Themes

Overview of menu.json

Customization of the images, names, tabs, and subtabs displayed in the navigation bar is handled through the menu.json customization file, located in your instance's "assets" directory, at: "/var/www/html/[instance name]/assets". 


Access menu.json by navigating to the assets directory: 

cd /var/www/html/[instance name]/assets


You may open the menu customization file, "menu.json" in vi, or another text editor:

sudo vi menu.json

When you view menu.json, tabs and their drop down sub-menu options are visible in a hierarchy organized by menu type. 

The top level of menu.json contains instance-wide settings for:

  • brandName - displayed company name
  • brandImage - logo image
  • brandUrl - default page at login
  • showCurrentReplicaServer- displays a small banner with the server hostname to which ProVision is currently connected

Below the instance wide settings are three top-level menu groupings, each containing their relevant tabs, subtabs, and menu settings.

In order, the three top menu groups are:

  • "footer_menu", containing settings for the Settings and Help menus
  • "menubar", containing settings for the standard provision navigation tabs and sub-tabs
  • "admin_menubar", containing settings for the admin area navigation tabs and sub-tabs

The second level of the hierarchy contains each navigation tab under that group, showing properties for name, visibility, url, and tab children. 

The third level, under "children" for a tab, lists the drop-down menu options available for the tab. Each child menu option has the same available properties, and can likewise be edited. 


Navigation Customization

Customize the Instance Logo / Name

The instance logo and company name displayed throughout ProVision may be edited to reflect your own company name and logo. 

In this example, we will change the topbar logo from the default (topbar-logo.png) to panda.png. You may also follow steps 2 and 3 to change the instance name ("brandName") referenced throughout ProVision.

Note: This action requires access and write permissions to your instance's "assets" directory

Tip - Before You Begin

Have your logo file ready to save into ProVision (png., .jpg, etc) ahead of time, and verify that the logo design is visible at small sizes, 48px or 64px wide.

There are no set size limitations, however ProVision will set the image to 48px wide by default. 

This size property can be adjusted in the custom css theme files by searching for the the css property: "--brand-image-width", and adjusting the pixel width accordingly.

Click the walkthrough below for detailed instructions:

Step 1: Save your desired logo into ProVision

Using the Command Line Interface (CLI), save the desired logo image file (here, "panda.png") to your instance's "assets" directory, located at: "/var/www/html/[instance name]/assets"

cd /var/www/html/[instance name]/assets

Step 2: Open the Menu Customization File

Open the menu customization file, "menu.json" in vi, or another text editor:

Note: Depending on available user permissions "sudo" may or may not be required.

sudo vi menu.json

Step 3: Change the brandImage / brandName Reference

At the top of the file, look for the "brandImage" attribute. By default, it should read "assets/topbar-logo.png". 

Edit the menu customization file to change the "brandImage" property to the new image name, here "assets/panda.png".

If needed, you may also update the "brandName" property to reflect your company or brand to match the new logo.

Save/write your changes to the file and exit. 

Clear your browser cached image files, and log into ProVision. The new logo image should be visible on the left side of the navigation menu.


Custom Navigation Menu Visibility

ProVision instances can be customized to adjust the visibility of menu tabs and sub-tabs, so that unused modules and pages may be hidden. 

In this example, we will hide the "IPAM" Tab from ProVision.

Note: This action requires access and write permissions to your instance's "assets" directory 

Expand the walkthrough below for detailed instructions on changing the visibility of Navigation menu items:


Step 1: Open the Menu Customization File

Using the Command Line Interface (CLI), navigate to your instance's "assets" directory, located at: "/var/www/html/[instance name]/assets"

cd /var/www/html/[instance name]/assets

Open the menu customization file, "menu.json" in vi, or another text editor:

Note: Depending on available user permissions "sudo" may or may not be required.

sudo vi menu.json

Step 2: Find the Tab in menu.json

When you view menu.json, tabs and their drop down sub-menu options are visible in a hierarchy organized by menu type. 

The top level of menu.json contains instance-wide settings for brandName (displayed company name), brandImage (logo), brandUrl (default page), and "showCurrentReplicaServer" (displays a small banner with the hostname of the server to which ProVision is currently connected). 

In order, the three top menu levels are:

  • "footer_menu", containing settings for the Settings and Help menus
  • "menubar", containing settings for the standard provision navigation tabs
  • "admin_menubar", containing settings for the admin area navigation tabs

Under each menu grouping, on the second level of the hierarchy, is each main menu tab. 

Each tab has properties for name, visibility, url, and tab children. 

The third level, under "children" for a tab, lists the drop-down menu options available for the tab. Each child menu option has the same available properties, and can likewise be edited. 

Since we are wanting to hide the "IPAM" tab in the standard area of ProVision, we need to scroll down to the "menubar" navigation grouping, and then find the second level tab with name "IPAM". 


Step 3: Change the Tab Visibility

Once you find the desired tab to hide, enter edit mode, then change the "visibility" property from "true" to "false" (do not include the quotes, and be sure to retain the trailing comma).

Save/write your changes to the file and exit. 


Step 4: View the Updated Navigation

Clear your browser cached image files, and log into ProVision.

The updated navigation should be apparent, in this case with "DNS", "DHCP", "IPAM", "Peering", and "Reporting" tabs no longer visible. 



Theme Customization

Two default ui themes are provided with ProVision - Light and Dark mode themes. Additional custom themes may be created and enabled to reflect company branding, if desired.

Themes are enabled on a per-user basis, by adjusting the Appearance settings available on the User Preferences page. 

Changing Themes

Users may select the desired theme by navigating to the User Preferences page and adjusting the Theming settings under "Appearance" as follows:

  • Light Mode Theme (default): Both "Enable Theming" and "Dark Theme" set to the OFF position
    • (Note: if no custom theme file exists, Light mode is also the fallback theme if "Enable Theming" is set to ON and "Dark Theme" is OFF)
  • Dark Mode Theme: Both "Enable Theming" and "Dark Theme" toggles set to ON
  • Custom Theme: If a custom theme file exists, set "Enable Theming" to ON, and "Dark Theme" to OFF to enable. If no custom theme file exists, this combination will fall back to Light Mode. 


Create a Custom Theme

A custom theme file may be used to customize colors, fonts, and sizing to reflect your company's branding. 

Note: Creating a custom theme requires strong CSS knowledge, as well as access and write permissions to your instance's "assets" directory

For a detailed walkthrough, expand the instructions below:


Step 0: Before You Begin

To customize the default theme and change how the application looks with CSS, you’ll need to add your own stylesheets or edit an existing theme file.

If you edit an existing theme file, we recommend making a copy of the existing file and keeping it as a backup file (.BKP).

The best practice is to manage your customizations in a new css file, using the information provided in the README.txt file under [ your instance directory ]/assets/css/custom (as seen below).

The README.txt file provides basic instructions as well as list of all available theming variables that may be used for a custom theme.

We recommend reviewing the README.txt file and becoming familiar with the available theme variables and what elements they affect in a small test theme file before finalizing your custom theme.

Step 1: Create a Theme file

In this example, we'll create a simple teal theme using some of these variables, which focuses on color and font changes to the top navigation menu, panels, and dashboard:

Step 2: Save the Theme File(s)

Once you are done, save your custom stylesheet file(s) into the assets/css/custom directory, like this:

└── assets/

     └── css/

         └── custom/

                ├── custom-theme-one.css

                ├── custom-theme-two.css

                └── custom-theme-three.css

Make sure that any files used for the intended theme use the .css extension, and any separate theme or backup theme files are changed to the .BKP extension.

If multiple css files are used for a theme, they will all be applied together as the final custom theme displayed.

In our example, we are using "custom-theme-simple.css" as our new primary theme file:

Step 3: Enable the Custom Theme in ProVision

Log into ProVision, and go to the User dropdown -> "User Preferences" → "Appearance". 

Under "Enable Theming", turn the toggle to the ON position, and verify that "Dark Theme" is turned to OFF (otherwise, Dark Mode theming will overwrite the custom theming files).

Once you're done, refresh the page and the custom theme should be visible. In some cases, you may need to empty your browser's cached images and files, and "Hard Refresh".

Here, we can see the new theme has changed the color and font of the top navigation menu, menu dropdowns, and panels.