Custom branding

Configure the look and feel of censhare Web with your organization's corporate design.

Introduction

In censhare WP, custom brandings are deployed as static webpack files. Therefore, custom brandings must be added to the project files before you build and start the censhare Server.

For a customized look and feel of the censhare Web user interface, you must change the following components:

• censhare Server - add CSS styles and logo, register the branding
• Keycloak - create a custom theme
• Cloud gateway - add the routing for branded resources on the static resource server 

To become effective, build and deploy the censhare Server with the webpacked resources, the Cloud gateway with the respective routings, and the Keycloak Server with a custom theme. After start up, the custom branding is available under the registered path. 

Customize default branding

This is the easiest way to customize censhare WP.

 No changes in  Cloud Gateway  configuration required.

 No custom logo

 Custom stylings are lost after system upgrade.  

Change default color scheme

To change the default color scheme, do the following:

1. On the censhare Server host, go to the censhare-product root directory.

2. Open the censhare-Client5/web/censhare.json configuration file in an editor.

3. In the brandings section, change the styles of the censhare5 branding:

   {
       "$schema": "./node_modules/@censhare/build-cli/schema.json",
       "release": {
           "locales": [
               "en",
               "de"
           ],
           "brandings": [
               {
                   "name": "censhare5",
                   "color20": "#5eabcf",
                   "color21": "#66b6dc",
                   "color22": "#69bee6",
                   "color23": "#b5dff2"
               }
           ]
       }
   }

   Other styles than color20, color21, color22 and color23 cannot be changed!

4. Save your changes.

Build webpack files

To apply the customized default color scheme, build the Webpack files and restart the restart the Static Resource Server (SRS).

Add a custom branding

This way to customize censhare WP allows you to add one or multiple custom brandings.

 Customizations are persistent also when upgrading the system.

 Multiple brandings applicabe

 Custom logo applicable

 Requires to change the Cloud Gateway configuration.  

Add custom color schemes

To add a custom color scheme, do the following:

1. On the censhare Server host, go to the censhare-product root directory.

2. Copy the censhare-Client5/web/censhare.json configuration file to the censhare-Custom/custom directory:

   cp censhare-Client5/web/censhare.json censhare-Custom/custom

3. For your convenience, rename the file, for example: customBranding.json.
4. Open the file in an editor.

5. In the brandings section, add a name and the styles for your custom branding:

   {
       "$schema": "./node_modules/@censhare/build-cli/schema.json",
       "release": {
           "locales": [
               "en",
               "de"
           ],
           "brandings": [
               {
                   "name": "censhare5",
                   "color20": "#5eabcf",
                   "color21": "#66b6dc",
                   "color22": "#69bee6",
                   "color23": "#b5dff2"
               },
               {
                   "name": "myCustomBranding",
                   "color20": "#5ecf61",
                   "color21": "#69e56c",
                   "color22": "#6ff272",
                   "color23": "#a6f2a8"
               }
           ]
       }
   }

   • The censhare5 section refers to the censhare default branding. Leave this section as is.
   • You can add multiple custom color schemes here. Make sure to use unique names.
   • Other styles than color20, color21, color22 and color23 cannot be changed!
6. To add multiple brandings, repeat the previous step. Ensure that you use unique names for your brandings. 
7. Save your changes.

Add custom logo

To add custom CSS styles, do the following:

1. On the censhare Server host, go to the censhare-product/censhare-Custom/custom directory.
2. Create a new directory called assets, and inside this directory, create a new directory called images.

3. Place your custom logo in the images directory. The file name must be as follows:

   logo_myCustomBranding.png

   • Use the same branding name as in the censhare.json configuration above.
   • Add a logo_ prefix.
   • Only PNG files are allowed.
4. For multiple custom brandings, add a logo for each branding with the respective name.

Build webpack files

Execute the following commands in the censhare-product root directory:

1. Run yarn to update the node modules.

2. Release the webpack files pointing to the custom configuration that you created:

   yarn cs5 release --config=../../censhare-Custom/custom/customBranding.json

This creates the static webpack files for each branding/locale combination.

Configure Cloud Gateway

To use custom brandings, you must configure the routing in the Cloud Gateway configuration. Do the following:

1. On the censhare Server host, go to the cloud-gateway root directory.
2. Open the application.yml configuration file.

3. Search for the default configuration at the end of the file:

   # default branding
   		- id: static_resources
             uri: ws://localhost:9000
             predicates:
               - Path=/censhare5/client/channel/
             filters:
               - RewritePath=/censhare5/client/(?<segment>/?.*)/, /webserver/websocket/$\{segment}
               - CustomTokenRelay

4. Add the following lines before the default configuration:

   # Routes to custom branding
   		- id: myCustomBranding_branding
             uri: [BASE_URL]
             predicates:
               - Path=/myCustomBranding/**
             filters:
   		 	- RewritePath=/MyCustomBranding/(?<segment>,*), /$\{segment}
   			- RewritePath=/MyCustomBranding, /
               - CustomTokenRelay
               - AddRequestHeader=Branding, myCustomBranding

   • Replace [BASE_URL] with the URL that you use to access censhare Web.
   • Use the same branding name as in the censhare.json configuration above.
   • In the id attribute, add the _branding suffix, in all other instances, use the branding name as is.
5. If you use multiple custom brandings, add a configuration for each branding.
6. Save your changes. 

Customize Keycloak

The look and feel of the login/logout page of Keycloak can be branded with a custom theme. For more information, see Create custom theme for Keycloak.

Result

The censhare login screen and main page are displayed in the customized layout.