Each product has a unique look and feel and they also use the common layout and design with each product. Carbon uses an overriding mechanism to achieve this. All the templates, css, and images are in the carbon core UI bundle which is named as “org.wso2.carbon.ui-<version-number>.jar”. (<version-number> is the particular version of the bundle). This bundle is responsible for the overall look and feel of the entire Carbon platform. In addition to this, each product has another style bundle which has all the overriding style sheets and images. For example WSO2 ESB has “org.wso2.esb.styles-<version-number>.jar”

In the following tutorial I am going to apply a completely different look and feel for the entire Carbon platform. Then I override that styles to get a distinguish design for a particular product.

The HTML template

I created an HTML template for this particular tutorial. This template is a simple blog type design. The design may not be appropriate for an application, but personally I like this kind of designs. This design uses a custom font from the free Google fonts. My design is dynamically applying the font to the design. Alternatively you can download it and import it using @font-face CSS attribute.

I included JQuery core library with the template file. I use JQuery to popup the menu on the top. It is also possible to use a CSS only menu. But it will require us to change the internal structure of the menu system, which runs out of scope of this tutorial.

Basically I am going to do few changes here.

1. Rotate the ESB logo and put it in the left side of the screen taking less space.
2. Replace the footer with a new big content filled one. (This is the trend these days.)
3. Remove the left side menu and place it in the header section as a popup menu.

Setting up the Development Environment

First of all you need to download the necessary files to follow this tutorial.

1. Download WSO2 ESB binary distribution- wso2.org/downloads/esb
2. Download the HTML theme that we are going to apply for the Carbon UI - simpletheme.zip

Extract the wso2esb-4.0.2.zip file in to a folder in your hard drive. As you already know all the images and CSS files are bundled in to jar files. If we have to do a change in one of these CSS files, we have to repack it, shutdown the server, deploy it, and start it again. This is not an option when you are doing User Interface design. Fortunately there is an easy way.

• Navigate to the "\repository\components\plugins" folder.
• Find “org.wso2.carbon.ui-3.2.2.jar”, and “org.wso2.esb.styles-4.0.2.jar”.
• Since jar files can be treated as zip files, you can extract them to two different folders.
  
• Remove the original two jar files.
• Now rename each folder adding a .jar at the end of each folder.
  
• Now start the server.

We can now directly edit the images, CSS, and JSP files inside these two folders and view their effect on the UI by just refreshing the browser.
We will be working with these two folders for some time. So it’s better if we can point our IDE to the "\repository\components\plugins" folder. Here is a screen shot of my project view. (IntelJIDEA community edition)

Copy New Files to carbon.core.ui Bundle.

• Copy style.css from the simpletheme folder to "\repository\components\plugins\org.wso2.carbon.ui-3.2.2.jar\web\admin\css".
• Copy logo.png from simpletheme folder to "\repository\components\plugins\org.wso2.carbon.ui-3.2.2.jar\web\admin\images".
• Copy script.js from simpletheme folder to "\repository\components\plugins\org.wso2.carbon.ui-3.2.2.jar\web\admin\js".

Ripping Off the Old CSS and Applying the New One.

Let’s remove the link to the global.css file from the main template file and add our styles.css file there. Now open ""\repository\components\plugins\org.wso2.carbon.ui-3.2.2.jar\web\admin\layout\template.jsp" file. This file contain the main layout of the page and default javascript library includes. Now go to line 32 and change the style sheet name from global.css to styles.css. If you try to preview Carbon console now, it will look messy.

Let’s make it even messier by striping out all the style from main.css file in "\repository\components\plugins\org.wso2.esb.styles-4.0.2.jar\web\admin\css\main.css"

Changing the Basic Layout of the Page.

template.jsp is the main layout page of the Carbon framework. Carbon layout use a Tiles jsp taglib. Tiles lets the user break the presentation page into small JSP snippets that perform a specific function but are not complete pages. For an example, the header part in template jsp file is replaced with the "<tiles:insertAttribute name="header"/>" tag. This tag refers to the header.jsp file which you can find in the same directory. When you are applying the new layout to the product, you have to modify the relevant tile pages as well. For our layout, we have to edit template.jsp, header.jsp and footer.jsp.

Make sure to keep the “ID” attributes as it is without changing or removing them. When editing the template.jsp you can remove the left side vertical tabs since we are going to move the whole menu to the header section as a drop down menu.

I am going to skip the steps that apply each HTML element to the template.jsp, header.jsp, and footer.jsp. You can download the finished files from here to continue with the tutorial.

Fixing the Top Menu

We moved the menu from left to the top of the page. Right now it’s not working as we expect. Let’s fix this.
Import the script.js file to template.jsp file. Go to line 101 in template.jsp and add the javascript file by adding the following line.

In Carbon UI bundles we are have several Javascript libraries. We have jQuery, YUI and prototype.js libraries. Since both prototype and jQuery have $ operation we are using the recommended method to avoid there possible conflicts. The jQuery core library’s $ operation is replaced with “jQuery”. This mean we have to replace all the $ in our scripts.js with jQuery.

jQuery(document).ready(
        function(){
            jQuery('.menuSection li.menu-header').click(function(){
                jQuery('.menuSection li.menu-header + li').hide();
                var next = jQuery(this).next();
                jQuery(next).show();
                var count=1;
                jQuery(document).click(
                    function(){
                        count++;
                        if(count ==3){
                            jQuery(next).hide();
                        }
                    }
                );

            });
        }
        );

A method use to toggle the menu is messing with our script, let’s remove the method content. Go to "\repository\components\plugins\org.wso2.carbon.ui-3.2.2.jar\web\admin\js\template.js". Find the method which has the signature as “function mainMenuCollapse(img)”, and remove its content and place a return; statement.

function mainMenuCollapse(img) {
    return;
}

If you follow along this tutorial you will have something like the following image.

Now this is the common UI for all the products. Let’s override few styles from the org.wso2.esb.styles-4.0.2.jar so that the styles are specific to the ESB product.

Fist of all copy logo-esb.png from “simpletheme” folder to "\ repository\components\plugins\org.wso2.esb.styles-4.0.2.jar\web\admin\images" folder. Now we need to override 4 styles. logo, headderStyle, headerInner, topmenuStyle. Copy the following code to the main.css file.

.logo{
    background:transparent url(../images/logo-esb.png) no-repeat left top;
}
.headderStyle{
    border-left:solid 8px #552988;
}
.headerInner{
    border-left:solid 8px #e8dcf5;
}
.topmenuStyle{
   border-left:solid 8px #e8dcf5;
}

We were able to re-theme the whole Carbon product platform within few steps. Of cause we need fine tuning for this theme. But I think this tutorial explain the basic process that need to follow.

Files ending with "_ajaxprocessor.jsp"

By default when create a jsp file ( say “foo.jsp”) in a Carbon UI component, it will inherit header, left menu and footer from the Carbon core UI. But if the file name is “foo_ajaxprocessor.jsp”, there will be no inheritance.

For an example let's consider, “login_ajaxprocessor.jsp” in “org.wso2.carbon.identity.saml.sso.ui” component. It simply omit the header, left menu and footer and display only the content from this file. So we are able to customize this page in to a different look and feel.

Author

Chanaka Jayasena, Senior Software Engineer, WSO2 Inc