Model: tool/Theme

Themes

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

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

Download and Update a Theme on the Legacy Admin Portal

Choose the hierarchy level at which the theme will be applied. Note that themes can only be customized by a Provider Administrator (or higher).
Choose Role Management > Themes to open the Themes list view.
Click the theme that you want to download.
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.
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.
- Headers are clearly marked and apply to design areas within the Admin Portal.
- Colors, sizes, fonts, images, and so on, can all be overwritten with the required formats.
- Images must be identified with the correct file path name. Preferably, do not use '/' preceding the path name; rather use relative paths, in other words a path relative to the CSS file location. For example, if your created an image sub-folder called 'img', use 'img/myimage.png'. After upload, the image should be viewable when opening the URL: http://<hostname>/www/themes/mytheme/img/myimage.png
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.
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".

All changes that are made directly in the CSS files will have to be manually carried over after each changes in the Less files.
Edit the Less files and compile them to get the new CSS files.
The aim with Less is that a theme can be customized with the minimum of technical knowledge (as with for example Twitter Bootstrap [http://getbootstrap.com/customize/>].

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:

Online [http://lesscss.org/usage/index.html#online-less-compilers>]
on your desktop [http://lesscss.org/usage/index.html#guis-for-less]
IDE [http://lesscss.org/usage/index.html#editors-and-plugins]

Theme Field Reference

Base

Title	field name	Description
Theme Name *	name	The name that is given to the Theme.
Navbar Text	banner_title	Text to display on the top navigation bar of the Admin Portal.
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 Portal.
Site Title	title	The title for the site
Import File *	import_file
Backup Enabled	backup	Create backup if existing theme exists

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

Model Details: tool/Theme

An asterisk * in the title indicates the field is mandatory.
If a field has a default value, it is shown in the Description column.
If the field type is an array, the Field Name has a .[n] suffix, where n is the array index placeholder.
Object and array field names are listed to provide context. If a field belongs to an object or an array, the full field name is shown in dot separated notation.

Title															Description																				Details