APIM 4.0.0 UI Customization Issue How To Fix Devportal And Publisher Title Problems

by ADMIN 84 views

Hey guys,

We've got a bit of a situation on our hands with the UI customization in APIM 4.0.0, specifically in the Devportal and Publisher. Sarindu Udagepala reported this on May 24, 2022, and it's something we need to iron out. Let's dive into the details, shall we?

Summary: The Title Tussle

The main issue is that changes made to the titles of the Devportal and Publisher via the userTheme.js file are only partially effective. This is a bug that's causing some headaches, and it's linked to Support Ticket APIMINTERNAL-2073. We're talking about APIM 4.0.0 here.

The Nitty-Gritty: Description of the Problem

This issue is also tracked on GitHub. We're dealing with version APIM 4.0.0, U2 Level 104. The core problem is that the title customizations aren't fully kicking in as expected.

Let's break it down for both the Devportal and Publisher.

Devportal: The Suffix Snafu

For the Devportal, the title suffix changes aren't showing up. Why? Well, there's a sneaky typo in the defaultTheme.js file. Check this out:

{{title: { prefix: '[Devportal]', sufix: '- WSO2 APIM', }}}

See that sufix? It should be suffix. This little typo is the culprit, preventing the suffix from being applied correctly. Typos can be so annoying, right? They always seem to pop up in the most crucial places!

Publisher: A Complete Title Lockdown

Over in the Publisher, it's even worse. Neither the title prefix nor the suffix changes are being reflected. It's like the userTheme.js file is whispering into the void. This is a bigger problem because it means that any custom branding or titling efforts are completely ignored.

Steps to Reproduce: Let's Get Our Hands Dirty

Okay, so how do we see this in action? Let's walk through the steps to reproduce the issue.

Devportal: The Suffix Struggle

  1. Open up the userTheme.js file in your Devportal.

  2. Add the following configuration:

    const Configurations = {
    /*
     This file can be used to override the configurations in devportal/source/src/defaultTheme.js
     ex. Uncomment the below section to enable the landingPage
     */
     custom: {
        title: {
            prefix: 'Custom title prefix',
            suffix: ' Custom title suffix',
        }
    }
};

  3. Restart the Devportal and check the title. You'll notice that the suffix changes aren't reflected. Bummer!

Publisher: The Prefix and Suffix Silence

  1. Now, let's head over to the Publisher and open its userTheme.js file.

  2. Add this configuration:

    /**
 * IMPORTANT: This file only contains theme JSS of the Publisher app, Don't add other configuration parameters here.
 * This theme file is an extension of material-ui default theme https://material-ui.com/customization/default-theme/
 * Application related configurations are located in `<PUBLISHER_ROOT>site/public/theme/settings.js`
 */
const userThemes = {
    light(theme) {
        return (
            {
                custom: {
                    title: {
                        prefix: '[DITT]',
                        suffix: 'Custom - WSO2 APIM',
                    }
                }
            }
        );
    },
};
if (typeof module !== 'undefined') {
    module.exports = userThemes; // Added for tests
}

  3. Restart the Publisher and... nothing. The prefix and suffix changes are nowhere to be seen. Double bummer!

Why This Matters: The Importance of UI Customization

UI customization is super important for several reasons. It's not just about making things look pretty (though that's a nice bonus!). It's about:

  • Branding: Custom titles and prefixes help reinforce your brand identity. When users see your application, you want them to know it's yours. Consistent branding builds trust and recognition.
  • Clarity: Custom titles can help users quickly identify which environment they're in (e.g., Dev, Staging, Production). This is crucial for avoiding accidental changes in the wrong place. Imagine deploying a change to production when you thought you were in staging! Yikes!
  • User Experience: A well-customized UI can improve the overall user experience. It makes the application feel more polished and professional.

Diving Deeper: The Technical Side

Let's get a little more technical. The userTheme.js file is designed to allow developers to override the default theme settings. This is a powerful feature, but it relies on the correct merging and application of these overrides. In this case, something's clearly going wrong.

The Devportal Typo: A Simple Fix

The Devportal issue is relatively straightforward. The typo in defaultTheme.js is preventing the suffix from being applied. A quick fix here would be to correct the spelling of sufix to suffix. This should resolve the suffix issue in the Devportal.

The Publisher Puzzle: A More Complex Challenge

The Publisher issue is a bit more complex. The fact that neither the prefix nor the suffix is being applied suggests that there might be a problem with how the userTheme.js file is being processed or how the title is being rendered in the UI. This could be due to a variety of factors, such as:

  • Incorrect file loading order
  • Issues with the theme merging logic
  • Errors in the component rendering code

Possible Solutions and Workarounds

So, what can we do about this? Here are a few potential solutions and workarounds:

For the Devportal:

  1. Immediate Fix: Correct the typo in defaultTheme.js. This should resolve the suffix issue.
  2. Long-Term: Ensure that code reviews catch these types of errors in the future. A second pair of eyes can often spot mistakes that the original author misses.

For the Publisher:

  1. Debugging: We need to dive into the Publisher's codebase and figure out why the title customizations aren't being applied. This might involve setting breakpoints, tracing the code execution, and examining the theme merging process.
  2. Workaround: As a temporary workaround, it might be possible to modify the title directly in the component rendering code. However, this is not ideal as it bypasses the intended customization mechanism.

The Road Ahead: Fixing the Bug and Preventing Future Issues

This UI customization issue is a prime example of why testing and code reviews are so important. A simple typo can have a significant impact on the user experience. We need to take a multi-pronged approach to address this:

  1. Fix the Bug: The immediate priority is to fix the typo in the Devportal and identify the root cause of the Publisher issue.
  2. Improve Testing: We need to enhance our testing processes to catch these types of issues early on. This might involve adding more unit tests and UI tests.
  3. Strengthen Code Reviews: Code reviews should be thorough and focus on both functionality and correctness. Catching errors during code review is much cheaper and faster than fixing them in production.
  4. Document the Solution: Once the issue is resolved, we should document the solution so that others can benefit from our experience. This will also help prevent similar issues from recurring in the future.

Conclusion: Let's Get This Sorted!

This UI customization issue in APIM 4.0.0 is a bit of a pain, but it's also an opportunity to improve our development processes. By fixing the bug, enhancing our testing, and strengthening our code reviews, we can ensure that our applications are not only functional but also user-friendly and well-branded. Let's roll up our sleeves and get this sorted out!