Customizing the Management Console

Some of the WSO2 products consist of a web user interface named the Management Console. It allows administrators to configure, monitor, tune, and maintain WSO2 products. The components that formulate the design and style of the Management Console are defined in resource (JAR) files. You can customize the Management Console 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 Management Console. 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/

Follow the steps below to change this logo.

Find the <IOTS_HOME>/wso2/components/plugins/org.wso2.carbon.ui_4.4.16.jar file, and extract it.

Find the bundle that contains the resource files you need to modify. In this case, the logo and the related CSS files are contained in the org.wso2.carbon.ui_4.4.16.jar file.
Create a new Maven project using your IDE (e.g. org.wso2.carbon.ui_4.4.16_patch ).

This creates a project for a new bundle to pack the files you modify. Since the symbolic name of the original bundle is ‘org.wso2.carbon.ui’, this patch bundle should have the symbolic name as part of its name (e.g. ‘org.wso2.carbon.ui_4.4.16_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.

Add the following content to the pom.xml file of the org.wso2.carbon.ui_4.4.16_patch project.

<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_4.4.16_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>

Create the web/, admin/, css/, images/ and layout/ directory locations as they were in the original bundle as shown in the file structure below.

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

This file includes the logo customization styles.

#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 customizations.css file to the <org.wso2.carbon.ui_4.4.16_patch>/web/admin/css/ directory.

This file includes the logo customization styles.
Copy the content of the <org.wso2.carbon.ui_4.4.16.jar>/ web/admin/layout/template.jsp file to the <org.wso2.carbon.ui_4.4.16_patch>/web/admin/layout/template.jsp file.
Add the following line to the <org.wso2.carbon.ui_4.4.16_patch> web/admin/layout/template.jsp file:
```
<link href="../admin/css/customizations.css" rel="stylesheet" type="text/css" media="all"/>
```
Add the below image as the new logo (e.g. new-logo.png) to the <org.wso2.carbon.ui_4.4.16_patch>/ web/admin/images/ directory.
Create another new Maven project using your IDE (e.g. o rg.wso2.carbon.ui_4.4.16_fragment).

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_4.4.16_fragment). This fragment bundle will not contain anything (expect the pom.xml file) when it is built.

Add the following content to the pom.xml file of the org.wso2.carbon.ui_4.4.16_fragment project.

This pom.xml file of the fragment bundle define properties including the required bundle value (i.e. ‘org.wso2.carbon.ui_4.4.16_patch’).

<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_4.4.16_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_4.4.16_patch</Require-Bundle>
                        <Fragment-Host>org.wso2.carbon.ui</Fragment-Host>
                    </instructions>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Build the following two projects by executing the following command: mvn clean install
- org.wso2.carbon.ui_4.4.16_fragment
- org.wso2.carbon.ui_4.4.16_patch
Once the project is built, copy the two JAR files (from the <PROJECT_HOME>/target/ directory) to the <IOTS_HOME>/dropins/ directory.
- org.wso2.carbon.ui_4.4.16_fragment-1.0.0.jar
- org.wso2.carbon.ui_4.4.16_patch-1.0.0.jar
Restart the WSO2 Carbon server.
Access the Management Console of WSO2 Carbon using the following URL: https://<IOTS_HOST>:9443/carbon (The default IoT Server host is localhost.)