[Index]

Model: data/Theme

Themes

To access the latest documentation, go to Documentation and Resources at: https://voss.portalshape.com

This section describes how to manage themes in the VOSS Automate legacy Admin portal.

Add a Theme in the Legacy Admin Portal

This procedure adds a theme on the legacy Admin GUI, and involves two steps:

  1. Prepare the theme file.
  2. Import the file to add the theme to the system.

Prepare a Theme File for Import

It is recommended that you use an export of an exiting theme as a baseline, and update it with a new name, images, and colours, as required.

Prerequisites:

To prepare the theme file:

  1. Create a folder with the same name as the theme you want to create, and unzip the exported theme to this folder.

    Note

    • Ensure you maintain the directory structure.
    • For the name of the folder, only alphanumeric characters or underscores are allowed. Do not use spaces or special characters.

  2. Add any CSS overrides to the file.

    Note

    You can only modify the definitions as shown in the export of a provided CSS file (skin.css).

  3. Add required image files to the folder (if any).

    For image filenames, you can use the following characters and character types:

    ALPHA / DIGIT / "-" / "." / "_" / "~"/ "#"

    Important

    If customization is done on MS Windows, check that no desktop.ini files reside in the directory tree of the theme before compressing it.

  4. Create a .zip archive file with the same filename as the folder.

Import a Theme File

This procedure imports a prepared file to add a theme in the legacy Admin Portal.

Pre-requisites:

To add a theme file to the Admin GUI:

  1. Log into the VOSS Automate Admin GUI (legacy).

  2. Choose the hierarchy level at which the theme will be created.

  3. Go to (default menu) Role Management > Themes.

  4. On the Themes list view, click Add to open the Themes page.

  5. On the Base tab:

    1. Add the theme name, which must be the same as the theme file name.

    2. Enter the navigation bar (navbar) text, if required. This text displays on the navigation bar next to the logo.

    3. Optionally, add a description.

    4. To apply the theme to the Login page, select Use this Theme to style Login page.

      Note

      Applies to the relevant Login page, either Self-service or Admin Portal. To change the banner text for the Login page, see Set the Login Page Theme.

    5. To prevent admins at lower levels of the hierarchy viewing this theme in the list view, select Hide from Lower Hierarchies.

    6. Add a site title, if required. The site title displays in the browser tab.

    7. Browse to the location of the theme zip file. Wait for the file to display in the Import File field.

    8. Optionally, select Backup Enabled to create a backup of the current theme on the server (if an existing theme file exists).

    9. Choose the interface where this theme will apply, either Administration (default) or Self-service.

  6. To customize the theme, update fields on the Theme Customization tab. See Create a Theme in the Business Admin Portal.

    Note

    All fields on this tab become mandatory once you enter any details on this tab.

  7. To customize the Login page, update fields on the Login Page Details tab. See Set the Login Page Theme

    1. Add a title for the top of the Login page.
    2. Add banner text.

  8. Click Save.

    Important

    Do not leave the screen until the theme processing completes and the theme list refreshes. This can take a few minutes, depending on the complexity of the theme you're uploading.

Download and Update a Theme on the Legacy Admin Portal

This procedure downloads an existing theme, edits it, and re-uploads it to the legacy Admin Portal.

Pre-requisites:

To download and update a theme:

  1. Log in to the legacy Admin Portal.

  2. Choose the hierarchy level at which the theme will be applied.

  3. Go to (default menu) Role Management > Themes.

  4. On the Themes list view, click on the theme you wish to download.

  5. Click Action > Download. The file is downloaded as a .zip archive with the name of the theme, and contains a folder with the theme name, and the following files:

    • skin.css
    • skin.less

  6. Edit the files.

  7. When editing is complete, ensure the directory folder name is the same as your theme name, then compress the folder and save the file with the theme name and a .zip file extension.

    Note

    • An error message displays if the file does not have a valid file extension.
    • Any files or folders inside the zip file archive that start with a '.' character are silently discarded when unzipping the theme. For example, if the zip archive contains any files named ._.DS_Store or .directory, these are ignored.

    Important

    If customization is done on MS Windows, check that no desktop.ini files reside in the directory tree of the theme before compressing it.

  8. Import the updated theme:

    Note

    No file upload is required if the theme update does not require an updated CSS in a zip file but only updates the text of the theme.

    1. Go to (default menu) Role Management > Themes
    2. On the Themes list view, click on the theme you're updating.
    3. On the Base tab, click Browse at the Import File field, and open a theme with the same name.
    4. Optionally, select Backup Enabled to create a backup of the current theme on the server.
    5. Click Save to complete the import process.

Customize Login Page Theme and Text in the Legacy Admin Portal

This procedure applies a theme and updates the text of the Login page, in the legacy Admin Portal.

  1. Log in to the legacy Admin Portal.

  2. Choose the hierarchy where the theme was created, or where it belongs.

  3. Go to (default menu) Role Management > Themes.

  4. On the Themes list view, click on the theme you want to use for the Login page.

  5. Update the Base tab:

    1. Select the Use this Theme to style Login page.

      Note

      When selecting this checkbox and a theme with the same Interface already has the Login page checkbox selected, this option is disabled on the existing theme as there can only be one Interface-Login page combination on the system.

      Any new themes, or updates to existing themes, may modify other themes on the system with the same Interface by disabling their Login page attributes.

      If no Interface is specified, the interface of the new Login theme defaults to Administration.

  6. Update the Login Page Details tab:

    1. Add title text, which is used for the top of the Login page.

    2. Add banner text (limited to 2048 characters), which is used at the bottom of the Login page.

      Add references to the cookie policy and privacy policy in the Banner Text field. These are added as placeholders:

      • {{cookie_policy}}
      • {{privacy_policy}}

      Note

      You can add multiple lines for the banner text, including paragraphs. Banner text displays exactly as you add it to this field. Cookie and security references show as links that open in a new browser tab.

    3. Optional. In the Cookie Policy field and the Privacy Policy field, add link text captions and a URL for each policy.

      Note

      Although the cookie and privacy policy references are optional, the captions and URLs are mandatory if they're used, and the placeholder references are then also required in the Banner Text field.

      For suggested input on the use of cookies by VOSS Automate in the cookie policy text, see VOSS Automate Cookie Policy.

      Browsers with blockers installed that prevent new tabs from opening will affect the functionality of links in the login banner.

      Privacy policy links can also be added to user menus. See Privacy Policy Menu Items and Manage Privacy Policy Menu Items.

      To customize the banner text style, see "Theme Banner Customization" in the Advanced Configuration Guide.

  7. Click Save.

Apply a Login Page Theme When Logging In

The Login page theme can also be applied to the login page during the log in process. To to this, add URL parameter theme=<theme-name> to the login request URL. This applies and overrides any theme that is set as the Login theme.

Note

For Self-service, if the theme value is set as login?theme=cisco_selfservice, the theme reverts to the Self-service theme set as the default.

For example, when two themes are available in the system, XYZ and ABC, and XYZ login page is set as default:

Controls appearance of web page

Model Details: data/Theme

Title Description Details
Theme Name * The name that is given to the Theme.
  • Field Name: name
  • Type: String
  • Pattern: ^[a-zA-Z0-9_]+$
Site Title Title displayed in the browser tab
  • Field Name: title
  • Type: String
Import File
  • Field Name: import_file
  • Type: String
  • Format: file
Import File Id
  • Field Name: import_file_id
  • Type: String
Backup Enabled Create backup if existing theme exists
  • Field Name: backup
  • Type: Boolean
Navbar Text Text that appears in the Navbar after login
  • Field Name: banner_title
  • Type: String
Description A description for the Theme.
  • Field Name: description
  • Type: String
Use this Theme to style Login page Determines if this theme is used to style the login page
  • Field Name: is_login_theme
  • Type: Boolean
Hide from Lower Hierarchies Indicates if the theme can be viewed and dowloaded at lower hierarchies.
  • Field Name: hide_from_lower_hierarchies
  • Type: Boolean
Interface The selected interface that is associated with the Theme. The interface can be an Administration or Self Service. Default: administration
  • Field Name: interface
  • Type: String
  • Default: administration
  • Choices: ["Administration", "Self Service"]
Theme Customisation The colours and images that comprise a theme.
  • Field Name: theme_customisation
  • Type: Object
Primary Colour This is the background colour for most menus and headers, as well as the text colour for links and buttons.
  • Field Name: theme_customisation.primary_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Primary Text Colour This is the text colour for anything with the primary colour background.
  • Field Name: theme_customisation.primary_text_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Accent Colour This colour is used when attention needs to be drawn for important notifications or active buttons and text.
  • Field Name: theme_customisation.accent_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Accent Text Colour This is the text colour for anything with the accent colour background.
  • Field Name: theme_customisation.accent_text_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Topbar Colour The colour used for the top bar of the site. Will use the primary colour if no value is given.
  • Field Name: theme_customisation.topbar_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Topbar Text Colour This is the text colour for the top bar. Will use the primary text colour if no value is given.
  • Field Name: theme_customisation.topbar_text_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Menu Colour The colour used for the menu on the left. Will use the primary colour if no value is given.
  • Field Name: theme_customisation.menu_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Menu Text Colour This is the text colour for the menu. Will use the primary text colour if no value is given.
  • Field Name: theme_customisation.menu_text_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Panel Colour The colour used for all the panels in the app.
  • Field Name: theme_customisation.panel_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Panel Text Colour This is the text colour for normal text in the app.
  • Field Name: theme_customisation.panel_text_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Input Colour The background colour for input fields. Will use the panel colour if no value is given.
  • Field Name: theme_customisation.input_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Input Text Colour The text colour for input fields. Will use the panel text colour if no value is given.
  • Field Name: theme_customisation.input_text_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Background Colour The colour of the background.
  • Field Name: theme_customisation.background_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Info Notification Colour The colour used for info notifications.
  • Field Name: theme_customisation.info_notification_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Info Notification Text Colour This is the text colour for info notifications.
  • Field Name: theme_customisation.info_notification_text_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Success Notification Colour The colour used for success notifications.
  • Field Name: theme_customisation.success_notification_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Success Notification Text Colour This is the text colour for success notifications.
  • Field Name: theme_customisation.success_notification_text_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Warning Notification Colour The colour used for warning notifications.
  • Field Name: theme_customisation.warn_notification_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Warning Notification Text Colour This is the text colour for warning notifications.
  • Field Name: theme_customisation.warn_notification_text_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Error Notification Colour The colour used for error notifications.
  • Field Name: theme_customisation.error_notification_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Error Notification Text Colour This is the text colour for error notifications.
  • Field Name: theme_customisation.error_notification_text_colour
  • Type: String
  • Pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
  • Format: color
Favicon The favicon for the site. Shown on the tab and when the site is bookmarked.
  • Field Name: theme_customisation.favicon
  • Type: String
  • Format: file
Favicon Id
  • Field Name: theme_customisation.favicon_id
  • Type: String
Logo This image is used for the logo in the top left of the menu bar. Must be a PNG image with a transparent background. Maximum file size is 0.5MiB and maximum dimensions are 600 pixels in width and 192 pixels in height.
  • Field Name: theme_customisation.logo
  • Type: String
  • Format: file
Logo Id
  • Field Name: theme_customisation.logo_id
  • Type: String
Login Logo This image is used for the logo on the login page. Must be a PNG image with a transparent background. Maximum file size is 0.5MiB and maximum dimensions are 600 pixels in width and 192 pixels in height.
  • Field Name: theme_customisation.login_logo
  • Type: String
  • Format: file
Login Logo Id
  • Field Name: theme_customisation.login_logo_id
  • Type: String
Login Background This image is used for the login screen background. Must be a PNG or JPEG image. Maximum file size is 5MiB and maximum dimensions are 1920 pixels in width and 1080 pixels in height.
  • Field Name: theme_customisation.login_bg
  • Type: String
  • Format: file
Login Background Id
  • Field Name: theme_customisation.login_bg_id
  • Type: String
Menu Background This image is used for the side menu background. Must be a PNG or JPEG image. Maximum file size is 2MiB and maximum dimensions are 240 pixels in width and 1040 pixels in height.
  • Field Name: theme_customisation.menu_bg
  • Type: String
  • Format: file
Menu Background Id
  • Field Name: theme_customisation.menu_bg_id
  • Type: String
Generate Admin GUI Theme Generate a new admin GUI theme, overwriting an existing theme of the same name
  • Field Name: theme_customisation.data_driven
  • Type: Boolean
Login Page Details How theme styles the login page
  • Field Name: login_page
  • Type: Object
Title Title displayed at top of login page
  • Field Name: login_page.title
  • Type: String
Banner Text Banner text displayed at bottom of login page. References to {{cookie_policy}} and {{privacy_policy}} will be replaced with relevant links when displaying the theme.
  • Field Name: login_page.banner
  • Type: String
  • MaxLength: 2048
Cookie Policy Reference to resultant hyperlink can be added as {{cookie_policy}} inside the Banner Text field
  • Field Name: cookie_policy
  • Type: Object
Link Text * Text that will be displayed for the hyperlink
  • Field Name: login_page.cookie_policy.text
  • Type: String
Link URL * URL that has Cookie Policy. Opens in a new tab
  • Field Name: login_page.cookie_policy.url
  • Type: String
Privacy Policy Reference to resultant hyperlink can be added as {{privacy_policy}} inside the Banner Text field
  • Field Name: privacy_policy
  • Type: Object
Link Text * Text that will be displayed for the hyperlink
  • Field Name: login_page.privacy_policy.text
  • Type: String
Link URL * URL that has Privacy Policy. Opens in a new tab
  • Field Name: login_page.privacy_policy.url
  • Type: String