New! JSON themes in Kopano WebApp

July 16, 2018

Von
Kategorie: blog
kopano webapp theming

WebApp theming has been around for a while now and has been a recurring workshop topic on the last few Kopano Conferences. It’s a great tool to modify colors, logo’s and even JavaScript. And while we got a lot of positive feedback on theming we realize building a plugin structure can be tricky to setup and debug, especially for designers who just want to design stuff and do not want to worry about JavaScript.

With the last thing in mind, we wanted to make theming easier. So we came up with “JSON themes“. A simple JavaScript Object Notation file to “brand” your WebApp. You tell us the colors and images that you want to use and we handle the rest.

How to create a JSON theme

  • Create a new directory in your WebApp plugin directory on your server. The name of the folder can be chosen freely, if no “display-name” is specified in theme.json then the name of the folder will also be the name of the theme.
  • In this new directory create a file called json.WebApp will now automatically detect this directory as a JSON theme.

In your theme.json you can specify the following pre-defined properties:

display-name = the name of the theme as shown in the theme drop-down in Settings
primary-color = the color of the main tab bar, the sign-in button and the title bar of the welcome page
primary-color:hover = the primary color for hovered buttons
action-color = the color of action buttons
action-color:hover = the color of hovered action buttons
selection-color = the color of selected elements
focus-color = the focus highlighting color
logo-large = the (relative or full) url of the logo used on the sign in page
logo-small = the (relative or full) url of the logo used inside the WebApp
background-image = the (relative or full) url of the background image of the login page
spinner-image = the (relative or full) url of the image used as spinner when logging in
stylesheets = the (relative or full) url to one or more css files. Can be a simple string for a single stylesheet or an array of strings for multiple stylesheets.

Important to know:

  • When a primary color is given but not the primary hover color, the latter will be generated automatically.
  • When an action color is given but not the action hover color, the latter will be generated automatically.
  • When a large logo is given but not a small logo, the large logo will also be used (resized by the browser) as a small logo
  • No property is mandatoryIf a property isn’t specified the default will be used (defined as the Basic theme of the WebApp or generated based on another property)

So a very simple branding theme.json could look like this:

{

"display-name": "Wikipedia",

"primary-color": "lightgrey",

"logo-large": "img/wiki_logo.png",

"background-image": "img/wiki_background.jpg"

}

// The images will be placed in a subdirectory with the name ‘img’ in this example

In this example the primary-color:hover will be generated based on the primary-color we defined, the action-color will be the one defined in the Basic theme of the WebApp, the logo-small will be the same as logo-large, and the spinner image will be the one defined in the Basic theme of the WebApp.

WebApp when the theme is enabled:

JSON themes in Kopano

The login screen, when the theme is set as default:

JSON login screen webappAdding custom CSS

For most themes, the pre-defined properties will be sufficient, but if you would like to change more styling in your theme (e.g. the font used) you can add custom stylesheets by adding the stylesheets property to your theme.json. The string(s) given here can be an absolute URL or a relative path (same as for the logo’s) The stylesheets are regular CSS files that are simply added to the WebApp.

Difference between a JSON theme and normal theme

If all you want to do is make some simple changes to “brand” the WebApp, JSON themes are the way to go. However, if you would like to make some changes to the UX design or change or add some functionality with your theme you will have to create a more powerful theme plugin. With a JSON theme, JavaScript cannot be added or changed.

Working Examples:

https://stash.kopano.io/users/rtoussaint/repos/themejsontest/browse

https://github.com/tsarbel/themebasicplus