This documentation is for WSO2 Carbon 4.4.3. View documentation for the latest release.
Page Comparison - Customizing the Management Console (v.2 vs v.3) - Carbon 4.4.3 - WSO2 Documentation
Due to a known issue do not use JDK1.8.0_151 with WSO2 products. Use JDK 1.8.0_144 until JDK 1.8.0_162-ea is released.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The user interfaces of every Carbon product allows you to configure, monitor, tune, and maintain WSO2 productsthe product. The components that formulate the design and style of these user interfaces are defined in resource (JAR) files. 

...

  • The common product layout/design inherited from the Carbon platform: All the common templates, styles (CSS files), and images are stored in the Carbon core UI bundle, which is named named 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.

  • The styles/images unique to each product: Each Carbon product (that is built on Carbon kernel) has another style bundle, which contains all the overriding style sheets and images: org.wso2.<product-name>.styles-<version-number>.jar.

You can customize the user interfaces by modifying these resource files. You need to create a fragment bundle for the original resource file that specifies a required bundle for it. Then, you can pack the modified resource files in the required bundle. The files in the required bundle will get precedence and will override the files in the original bundle.

You can use this same technique to customize any aspect of the user interfaces. The advantage of this technique is that you will not lose your customizations when you apply official patches to the product by replacing the original bundles.

For example, when you access the Management Console using the following URL, by default, it has the WSO2 product logo as shown below: https://10.100.5.72:9443/carbon/

Info

You view all images in this guide when you follow these instructions for WSO2 Note that the images and instructions given on this page are valid for WSO2 products that are based on Carbon 4.4.6x.

current logo of the Management Console

Follow the steps below to change this customize the above management console by changing the logo.

  1. Find

    Find the Open the <PRODUCT_HOME>/repository/componentcomponents/patchesplugins/org.wso2.carbon.ui_<version-number>.jar file, and extract it.

    Tip

     directory. You need to find the bundle that contains the resource files that you

    need

    want to modify. In this case, the logo and the related CSS files are contained

    in the

    in the org.wso2.carbon.ui_<version-number>.jar

    file.

     Create a new Maven project using your IDE (e.g. org. file. Copy the org.wso2.carbon.ui_<version-number>.jar file to a separate location on your computer, and extract the file. Note the symbolic name of this bundle, which is 'org.wso2.carbon.ui_<version-number>_patch)'

  2. InfoThis creates a project for a new bundle to pack the files you modify. Since the

    Create a new Maven project using your IDE. Be sure to include the symbolic name of the original bundle

    is ‘

    that you extracted in the previous step (which is 'org.wso2.carbon.ui

    ’, this patch bundle should have the symbolic name as part of its name (e.g. ‘org.

    _<version-number>') in the Maven project name. For example, you can use org.wso2.carbon.ui_<version-number>_patch

    ’). Also, you need to use this name with the symbolic name as part of it, as the required bundle in the fragment bundle, which you will create later.

     as the Maven project name. 

  3. Add the following content to the to the pom.xml file of the  file of the  org.wso2.carbon.ui_<version-number>_patch project.     In this pom.xml file, be sure to replace the <version-number> of org.wso2.carbon.ui_<version-number>_patch with the correct version value.

    Code Block
    languagexml
    <?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>
    
        <groupId>org.wso2.carbon</groupId>
        <artifactId>org.wso2.carbon.ui_<version-number>_patch</artifactId>
        <version>1.0.0</version>
        <packaging>bundle</packaging>
    
        <build>
            <plugins>
                <plugin>
                    <groupId>org.apache.felix</groupId>
                    <artifactId>maven-bundle-plugin</artifactId>
                    <version>3.0.1</version>
                    <extensions>true</extensions>
                    <configuration>
                        <instructions>
                            <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
                            <Bundle-Name>${project.artifactId}</Bundle-Name>
                            <Export-Package>web.admin.*</Export-Package>
                        </instructions>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </project>
  4. Create directories in your Maven project as explained below.

    1. Create the /web folder under the /

    admin/, css/, images/ and layout/ directory locations as they were in the original bundle as shown in the file structure below. file structureImage Removed
    1. src/main/resources directory of the org.wso2.carbon.ui_<version-number>_patch project. 

    2. Then, create the /admin directory under /web. 

    3. Finally, create the /css, /images, and /layout directories under /admin

    Your org.wso2.carbon.ui_<version-number>_patch project should now look as shown below.
    Image Added

  5. Create a new CSS file (e.g. customizations.css with the following content.

    Code Block
    languagecss
    #header div#header-div div.left-logo {
    	background-image: url( ../images/new-logo.png );
        background-repeat: no-repeat;
        background-position: left top;
        background-size: contain;
    	height: 40px;
    	width: 300px;
    	margin-top: 23px;
    	margin-left: 20px;
    	float: left;
    }
    Add the 
    Tip

    This file includes the logo customization styles. 

  6. Add the customizations.css file to the  file to the <org.wso2.carbon.ui_<version-number>_patch>/src/main/resources/web/admin/css/ directory.  

    Tip

    This file includes the logo customization styles. 

  7. Copy the content of the Locate the template.jsp file that is in the org.wso2.carbon.ui_<version-number>.jar bundle, which you extracted in step 1 above. You will find template.jsp file inside the  <org.wso2.carbon.ui_<version-number>.jar>/ web/admin/layout/template.jsp file to the  directory. Then, copy this file to the <org.wso2.carbon.ui_<version-number>_patch>/src/main/resources/web/admin/layout/template directory.jsp file.

  8. Add Locate the following line to the in the <org.wso2.carbon.ui_<version-number>_patch>/ src/main/resources/web/admin/layout/template.jsp file

    Code Block

    , which you added in the previous step:

    Code Block
    <link href="<%=globalCSS%>" rel="stylesheet" type="text/css" media="all"/>
  9. Replace the above line with the following:

    Code Block
    languagejava
    <link href="../admin/css/customizations.css" rel="stylesheet" type="text/css" media="all"/>
  10. Add the below image as the new logo (e.g.  new-logo.png) to the  <orgthe <org.wso2.carbon.ui_<version-number>_patch>/src/main/resources/web/admin/images/ directory.

    new logo

  11. Create another new Maven project using your IDE (e.g. Be sure to include the symbolic name of the original bundle that you extracted in step 1 above (which is 'org.wso2.carbon.ui_<version-number>') in the project name. For example, you can use org.wso2.carbon.ui_<version-number>_fragment) as the Maven project name. 

    Info

    This creates a project for the fragment bundle. Since the symbolic name of the original bundle is ‘org.wso2.carbon.ui’, the fragment host value of this bundle should be the same (e.g. o rg.wso2.carbon.ui_<version-number>_fragment). This fragment bundle will not contain anything (expect the pom.xml file) when it is built.  

  12. Add the following content to the to the pom.xml file of the  file of the org.wso2.carbon.ui_<version-number>_fragment project. In this pom.xml file, replace the <version-number> of org.wso2.carbon.ui_<version-number>_patch and org.wso2.carbon.ui_<version-number>_fragment with the correct version value.

    Info

     This pom.xml file of the fragment bundle definedefines properties including , which includes the required bundle value (i.e. ‘org.wso2.carbon.ui_<version-number>_patch’). 


    Code Block
    languagexml
    <?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>
    
        <groupId>org.wso2.carbon</groupId>
        <artifactId>org.wso2.carbon.ui_<version-number>_fragment</artifactId>
        <version>1.0.0</version>
        <packaging>bundle</packaging>
    
        <build>
            <plugins>
                <plugin>
                    <groupId>org.apache.felix</groupId>
                    <artifactId>maven-bundle-plugin</artifactId>
                    <version>3.0.1</version>
                    <extensions>true</extensions>
                    <configuration>
                        <instructions>
                            <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
                            <Bundle-Name>${project.artifactId}</Bundle-Name>
                            <Require-Bundle>org.wso2.carbon.ui_<version-number>_patch</Require-Bundle>
                            <Fragment-Host>org.wso2.carbon.ui</Fragment-Host>
                        </instructions>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </project>
  13. Build Now you can build the following two projects by executing the Open a terminal, navigate to the relevant project directory (listed above), and execute the following command: mvn clean install. 
    • org.wso2.carbon.ui_<version-number>_fragment

    • org.wso2.carbon.ui_<version-number>_patch 
  14.    Once the project is built, copy the two JAR files listed below (from the from the <PROJECT_HOME>/target/ directory) to the <CARBONto the <PRODUCT_HOME>/repository/components/dropins/ directory.
    • org.wso2.carbon.ui_<version-number>_fragment-1.0.0.jar

    • org.wso2.carbon.ui_<version-number>_patch-1.0.0.jar
  15. Restart the WSO2 Carbon product server.
  16. Access the Management Console management console of your WSO2 Carbon product using the following URL:
     https://10.100.5.12:9443/carbon/You view the new logo, which the patch bundle contains as shown below.

    Management Console with the new logoImage Modified