Customizing OEM Edition

Prerequisites

Before going further, make sure that we have successfully completed the exercise from "Building and Deploying OEM Edition".

OEM Project

OEM Project is oem-enterpriseweb-{versionNumber}-{buildHash}.tar.gz found in the OEM package.

It provides a structured starting point to replace default UI components, branding elements and functionalities which allows us to deliver a personalized version of the Joget platform.

We can customize:

• Landing and console pages
• Styles and branding like colors, logos and icons
• Default apps and App Center
• Custom labels, links and plugin behaviors

The default setup includes a basic blue theme, which we can freely adjust to fit customized branding and requirements.

Few context before we begin customizing:

• All images included in the OEM Project are already sized appropriately for where they are used in the UI.
  When replacing them, make sure the new images match the original dimensions to maintain proper layout and appearance.
• We may modify or replace any files necessary to align with custom branding and functional requirements.
• The sample Java plugin implementations included in the OEM Project are meant for reference.
  For production use, it's recommended to create and maintain plugin classes in a separate JAR module.

Key Customization Areas

Below key areas can be found in oem-enterpriseweb-{versionNumber}-{buildHash}.tar.gz.

1. Landing and Home Pages

• src/main/webapp/index.jsp: The first page when accessing the system.
• src/main/webapp/home/index.html: Main landing page that appears after login.

2. Web Console UI

• src/main/webapp/WEB-INF/jsp/console/home.jsp: Console homepage shown after a user logs in.
• src/main/webapp/WEB-INF/jsp/console/welcome.jsp: Content panel on the right side of the console home screen.

3. Error Pages

• src/main/webapp/WEB-INF/jsp/error404.jsp: Custom “Page Not Found” page.
• src/main/webapp/WEB-INF/jsp/error500.jsp: Custom “Internal Server Error” page.

4. Custom CSS Files

Below files is located in src/main/webapp/css/ folder:

• admin_bar_custom.css: Styles for the admin bar at the top of the interface.
• builder_custom.css: Styling used by the form and app builders.
• console_custom.css: Styling for the web console layout and elements.

5. Custom Images

Images are located in src/main/webapp/images/custom/ folder. We can replace these with custom branded versions. Just make sure the new images have the same dimensions as the originals so they fit into the UI properly.

Other important icons:

• /images/favicon.ico: Favicon for the web console.
• /images/favicon_uv.ico: Favicon for userviews.

6. Spring Context and Resource Bundles

• src/main/resources/customApplicationContext.xml: Used to define custom Spring beans or perform additional property initialization.

• src/main/resources/custom.properties: Contains custom label definitions, link settings and localized text overrides.
  To override default values, follow below steps:

  1. Identify the keys to override from the properties files located in target/jw/WEB-INF/classes/*.properties.
  2. Add the overrides into src/main/resources/custom.properties.

Customizing the App Center

The App Center is the screen users see to manage and launch apps. Joget installs the default App Center from this file during system initialization:

/src/main/resources/setup/apps/APP_appcenter-1.zip

We can replace this file with a customized version of the App Center app. Just make sure the filename remains APP_appcenter-1.zip.

If we're using the default App Center app and want to change the Marketplace link, edit the first Custom HTML element in the Published Apps form.

To set up trusted URLs for Marketplace downloads, define them in custom.properties:

appCenter.link.marketplace.trusted=https://your-marketplace-url.com

Setting Up Default Apps

To bundle custom default apps with the installer:

1. Copy new app ZIP files into /src/main/resources/setup/apps/ folder

2. Edit /src/main/resources/setup/setup.properties file and define the paths to newly added apps.

3. If needed, we can also package a customized default database to go along with our build.

Customizing the License Purchase Link

In the Settings screen, we can customize or hide the "Purchase License" link.

To change the label and URL, add the following to src/main/resources/custom.properties:

license.purchase=Buy a License
license.purchase.url=https://your-licensing-page.com

If we want to hide the link, leave the URL value empty.

Rebuild and redeploy OEM Edition

Once we are done with our customizations, follow these steps to build and deploy it using the terminal:

1. Navigate to the OEM Project directory:

   cd oem-enterpriseweb-9.0.0-958f479

2. Build the OEM Project:

   mvn clean install -Dmaven.test.skip=true

3. Stop running the Joget instance.

4. Clean up existing deployed Joget:

   • Delete the jw folder in tomcat/webapps/ and jw.war
   • Delete all files and folders in Tomcat temp/* and work/* folders

5. Copy the newly build oem-enterpriseweb-9.0.0-958f479/target/jw.war to the {jogetInstallationFolder}/apache-tomcat-*/webapps/ folder

6. Start up Joget.

7. Once the Joget instance is ready, go to http://localhost:8080/jw to confirm that the changes made are applied correctly.

Tips

• Stick to the same image dimensions when replacing logos and icons to maintain layout and alignment.
• Implement actual plugins in a separate project to keep things clean and manageable.
• Avoid changing Joget core files directly. Use the OEM Project as a layer of customization.
• Always check the server logs if things don’t display or behave as expected. Missing properties or JSP errors are usually caught there.
• Use Git or a similar version control system before starting any customization. It's a great way to record and track customizations being made.