[Index]

Model: tool/Theme

Themes

Full HTML Help

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.

      Note

      Valid characters allowed for the theme name are in the range: a-zA-Z0-9_

    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.

Themes

  1. Prepare the theme file:

    1. The recommended procedure is to use an export of an exiting theme as a baseline and update it with a new name, images and colours as required. Refer to Download and Update a Theme for details.

    2. Create a folder with the required name of the theme and un-zip the exported theme in it, maintaining directory structure.

      The name of the folder must be the same as the intended theme name (only alphanumeric characters or underscore can be used, with no spaces or special characters).

    3. Add any CSS overrides to the file. Note that only the definitions as shown in the export of a provided CSS file skin.css can be modified.

    4. Add required image files in this folder (if any).

      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.

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

  2. Add the theme to the system:

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

    2. Choose Role Management > Themes to open the Themes list view.

    3. Click Add on the button bar to open the Themes input form. Note that themes can only be customized by a Provider Administrator (or higher).

    4. Enter the Theme Name (same as the file name created above).

    5. Enter Navbar Text if needed. This will show on the navigation bar next to the logo.

    6. Enter an appropriate Site Title if required. The site title entered here is the text displayed in the browser tab.

    7. Click the Browse button to import the created theme zip file. Wait until the system displays the file chosen in the Import File field.

    8. If the theme must also apply to the login page, select the Use this Theme to style Login page check box.

    9. To set login banner text and notices on the login page, refer to Set the Login Page Theme. The Use this Theme to style Login page check box does not have to be selected for banner text to show.

    10. If you want to hide the theme from lower level hierarchies, select the Hide from Lower Hierarchies check box. Users logged in at lower level hierarchies will not be able to see that particular theme on the Themes list view screen.

    11. For details on the Theme Customization tab controls, refer to Create a Theme in the Business Admin Portal.

      Note

      If any details are added on this tab, all fields should be provided with input.

    12. Choose Interface to which the theme applies from the drop down. By default the theme applies to the Administration interface.

    13. Click Save on the button bar when complete.

      Note

      Do not leave the screen until the processing of the theme completes and theme list is refreshed. This can take a few minutes depending on details and complexity of theme uploaded.

Themes

Themes control the look and feel of the entire GUI interface. This contains all aspects of the presentation including the images, logos, colors, fonts, sizing and positioning.

New themes can be added and existing themes can be edited. These are associated with a user's role. There is no limit to the number of themes that can be added and applied. It is a common practice to have a theme associated with a specific customer (company).

The default theme that applies to the GUI when the system is initially built, is available on the VOSS-4-UC system and can be used as the baseline template. The theme is in the form of a Cascading Style Sheet (CSS) to be exported, edited and re-imported as required.

While all aspects of the exported CSS can be modified, we recommend that the default theme is used as a template in terms of basic design in order to prevent usability or functional issues.

The CSS file itself is simple to export and edit. Clear headers in the CSS file indicate which area of the GUI the design applies to. The headers include the following components:

Images can be stored with the theme or referenced with the use of relative path names.

The ability to view themes created at a given hierarchy level can be restricted from users at a lower hierarchy level by use of the Hide from Lower Hierarchies check box. If this check box is checked for a particular theme, that theme will no longer be visible on the Themes list view screen at the lower level hierarchy.

The theme feature is applied to either the Administration or Self-Service interface. If no Interface is specified, the new login theme will also have its interface set to Administration.

It also includes a Use this Theme to style Login page check box, which when selected, applies the chosen look and feel to the Login page across the system. Currently, the system allows only a single theme to be applied to the Login page per Interface. This means that a new or updated theme with Interface and Login page setting that corresponds to an existing theme, will result in the disabling of the Login page style on an existing theme with the same Interface setting.

The Login page theme can also be applied to the Login page during the log in process by adding a suffix to the login request url. See 'Set the Login Page Theme'.

Download and Update a Theme on the Legacy Admin Portal

  1. Choose the hierarchy level at which the theme will be applied. Note that themes can only be customized by a Provider Administrator (or higher).

  2. Choose Role Management > Themes to open the Themes list view.

  3. Click the theme that you want to download.

  4. Click Action > Download on the button bar to download the theme. The exported file is a .zip archive with the name of the theme. The archive contains a folder with the theme name and files called skin.css and skin.less in it.

  5. Refer to the recommended practice to edit the Less file at the end of this topic, otherwise save the file and open the CSS file in a text editor.

  6. When editing is complete, make sure the directory folder name is the same as your theme name. Compress the folder and save the file with the theme name and a .zip file extension.

    An error message will display on the user interface if the file does not have a valid file extension.

    Note that any files or folders inside the zip file archive that start with a '.' character will be silently discarded when unzipping the theme. For example, if the zip archive contains any files named ._.DS_Store or .directory, they will be 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.

  7. Choose Themes:

    1. For an update, choose the theme name and click Browse adjacent to Import File and then open the same theme name. Optionally select the Backup Enabled check box to create a backup of the current theme on the server. Click Save to complete the import process.

      If a theme update does not require an updated CSS in a zip file but only updates the text of the theme, then no file upload is required. For information about the other fields on this form, refer to the topic on adding a theme.

    2. To delete a theme, choose it from the list and click Action > Delete.

The preferred way to edit a theme is to edit and compile the Less files. Refer to the "Less files and Theme Customization" topic in the "Advanced Configuration Guide".

For an introduction to Less, visit the official website [http://lesscss.org/]. To compile the Less theme, a Less compiler is required. The following list shows examples:

Download, Edit and Update a Theme

  1. Choose the hierarchy level at which the theme will be applied. Note that themes can only be customized by a Provider Administrator (or higher).

  2. Choose System Configuration > Themes to open the Themes list view.

  3. Click the theme that you want to download.

  4. Click Download on the button bar to download the theme. The exported file is a .zip archive with the name of the theme. The archive contains a folder with the theme name and files called skin.css and skin.less in it.

  5. Refer to the recommended practice to edit the Less file at the end of this topic, otherwise save the file and open the CSS file in a text editor.

  6. When editing is complete, compress the folder and save the file with the .zip file extension. The downloaded build_dependencies/ subdirectory does not need to be included for compression and upload.

    An error message will display on the user interface if the file does not have a valid file extension.

    Note that any files or folders inside the zip file archive that start with a '.' character will be silently discarded when unzipping the theme. For example, if the zip archive contains any files named ._.DS_Store or .directory, they will be ignored.

  7. Return to System Configuration > Themes:

    1. For an update, select the theme name and click Browse adjacent to Import File and then open the same theme name. Optionally check the Backup Enabled check box to create a backup of the current theme on the server. Click Modify to complete the import process.
    2. For a new theme, enter a theme name that is the same as the new .zip archive filename. Click Modify to complete the import process.
    3. To delete a theme, select it from the list and click Delete.

The preferred way to edit a theme is to edit and compile the Less files.

For an introduction to Less, visit the website [http://lesscss.org/]. To compile the Less theme, a Less compiler is required. The following list shows examples:

Theme Field Reference

Base

Theme Name * name The name that is given to the Theme.
Use this Theme to style Login page is_login_theme Should Login page use this theme? Applies to the relevant theme's login page: either the Self-service or admin.
Site Title title The title for the site
Import File * import_file  
Backup Enabled backup Create backup if existing theme exists

Login Page Details

Title title Title displayed at top of login page.
Banner text banner Banner text displayed at bottom of login page.

Add a Theme

  1. Prepare the theme file

    1. Create a folder and add a file skin.css with the required name of the theme. The name of the folder must be the same as the intended theme name (only alphanumeric characters can be used, with no spaces or special characters).
    2. Add any CSS overrides to the file. Note that only the definitions as shown in the export of a provided CSS file skin.css can be modified.
    3. Add required image files in this folder (if any).
    4. Optionally create a settings.json file in the theme folder. The settings.json has flags that controls overall appearance of elements on pages. Refer to the Theme Settings reference topic.
    5. Create a .zip archive file with the same filename as the folder.

  2. Add the theme to the system

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

    2. Choose System Configuration > Themes to open the Themes list view.

    3. Click Add on the button bar to open the Themes input form. Note that themes can only be customized by a Provider Administrator (or higher).

    4. Enter the Theme Name (same as the file name created above).

    5. Enter an appropriate Site Title if required. The site title entered here is the title displayed in the browser tab.

    6. Click the Browse button to import the created theme zip file. Wait until the system displays the file chosen in the Import File field.

    7. If the theme must also apply to the login page, check the "Use this Theme to style Login page" check box. Refer to the step on selecting the Interface below for the effect on existing themes if this option is selected.

    8. If you want to hide the theme from lower level hierarchies, check the "Hide from Lower Hierarchies" check box. Users logged in at lower level hierarchies will not be able to see that particular theme on the Themes list view screen.

    9. Select the Interface to which the theme should apply. The available options are Administration or Self Service. If no Interface is specified, the new login theme will also have its interface set to Administration.

      There can only be one Interface-Login page pair on the system. In other words, if the new or updated theme has been set to also style the Login page, any existing themes that have the same Interface and style the Login page, their Login page style setting is disabled.

    10. Click Save on the button bar when complete.

Set the Login Page Theme

  1. Choose the hierarchy level in which the theme was created or to which the theme belongs.

  2. Choose System Configuration > Themes to open the Themes list view.

  3. Click the required Theme Name that you want to use for the Login page.

  4. On the Base tab, check the Use this Theme to style Login page check box.

    If the check box is enabled and a theme with the same Interface already has the Login page check box enabled, this will result in the disabling of the check box on the existing theme. There can only be one Interface-Login page combination on the system, so that 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 new login theme will also have its interface set to Administration.

  5. On the Login Page Details tab, enter the required text in the Title field and Banner text field. The text entered in the Title field will be displayed at the top of the Login page, above the logo. The text entered in the Banner Text field will be displayed at the bottom of the Login page, below the Log In button.

  6. Click Save on the button bar when complete to implement the selection.

The Login page theme can also be applied to the login page during the log in process. Do this by adding the suffix '?theme=default' to the login request url. For example: https://instance/login/?theme=default, where 'default' is one of the themes available in VOSS-4-UC. This usage in the URL will apply and override any theme that is set as the login theme.