Monday, August 9, 2021

Changing the WSO2 Management console's interface

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

The user interface of every Carbon product consists of two layers:

  • 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 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. 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.



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

  1. Open the <PRODUCT_HOME>/repository/components/plugins/ directory. You need to find the bundle that contains the resource files that you want to modify. In this case, the logo and the related CSS files are contained in the org.wso2.carbon.ui_<version-number>.jar 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>
  2. Create a new Maven project using your IDE. Be sure to include the symbolic name of the original bundle that you extracted in the previous step (which is org.wso2.carbon.ui_<version-number>) in the Maven project name. For example, you can use org.wso2.carbon.ui_<version-number>_patch as the Maven project name. 
  3. Add the following content to the pom.xml 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. (ex: org.wso2.carbon.ui_4.5.3_patch)

  4. Create directories in your Maven project as explained below.
    1. Create the /web folder under the /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.


  5. Create a new CSS file (e.g. customizations.css with the following content and Add the customizations.css file to the org.wso2.carbon.ui_<version-number>_patch/src/main/resources/web/admin/css/ directory. This file contains the logo customization styles.

  6. 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/ directory. Then, copy this file to the org.wso2.carbon.ui_<version-number>_patch/src/main/resources/web/admin/layout/ directory.
  7. Add below line into this template.jsp file. <link href="../admin/css/customizations.css" rel="stylesheet" type="text/css" media="all"/>

  8. You can update the Title and the favicon as well.

  9. Add the new image as the new logo (e.g.  new-logo.png) to the org.wso2.carbon.ui_<version-number>_patch/src/main/resources/web/admin/images/ directory.
  10. Create another Maven project using your IDE. 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. 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. org.wso2.carbon.ui_<version-number>_fragment). This fragment bundle will not contain anything (expect the pom.xml file) when it is built.
  11. Add the following content to the pom.xml 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. This pom.xml file of the fragment bundle defines properties, which includes the required bundle value (ex: org.wso2.carbon.ui_<version-number>_patch)
     

  12. Now you can build the two projects. 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 

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

    • org.wso2.carbon.ui_<version-number>_patch-1.0.0.jar

  14.  Restart the WSO2 product server.
  15. Access the management console of your WSO2 product using the following URL: https://localhost:9443/carbon/You view the new logo, which the patch bundle contains as shown below.