Site Branding - Theme colors and logo config

[milospp]

VIVO GitHub issue
Linked Vitro PR

What does this pull request do?

This pull request allows administrators to customize institutional branding by defining institutional colors and updating the key color scheme of the current theme.

What's new?

1. Theme Color Customization
   Administrators can now change the following theme colors:
   • Primary Color
   • Secondary Color
   • Accent Color
2. Advanced Color Options
   Additional options for detailed customization:
   • Primary Lighter Color
   • Primary Darker Color
   • Link Color
   • Text Color
3. Logo Management
   • Option to upload a custom logo (max aspect ration 1:7).
   • Option to upload a smaller logo that is visible when screen is smaller (max aspect ration 1:3).

The theme editor is fully customizable per theme.
Each theme’s colors are defined in:
webapp/themes/{theme}/theme-config.json

{
  "themeName": "string",              // Name of your theme
  
  "themeColors": {
    "palette": [                 
      {
        "groupName": "string",         // Logical group (primary, secondary, accent, text, etc.)
        "colors": [
          {
            "name":        "string",        // script identificator name (e.g. primary-base)
            "value":       "hex|string",   // Explicit hex color
            "cssVariable": "string",     // The actual CSS variable that will be injected into :root (Example: "--primary-color")
            "hidden":      true|false,    // (optional) Hides the color from the theme editor / UI color picker.  
                                                       // Commonly used for auto-generated shades that should not be edited directly.shading )
            
            "shade": {                          // (optional) Auto-generate this color from another base color
              "type":   "lighten|darken", // What kind of adjustment
              "amount": number,         // Percentage points (0–100). 20 ≈ 20% lighter/darker
              "base":   "string"            // Name of the base color inside the same theme file
            }
          }
          // ... more colors in the group
        ]
      }
      // ... more groups
    ]
  }
}

Screenshoots

The chain icon indicates that the shade is linked to its base color and will update automatically when the base changes. If the user manually edits a shade, the chain breaks (turns off). To re-link it and restore automatic updates, click the Reset button in the group.

How should this be tested?

General Testing

Ensure testing is conducted for every available theme.

Test 1: Theme Colors

1. Select a theme
2. Customize colors (Primary, Secondary, Accent)
3. Verify that the updated colors are applied across the site

Test 2: Logo Upload

1. Click Change LOGO
2. Upload a logo image
3. Crop and save the logo
   • Ensure cropping is restricted to a 1:1 or wider aspect ratio.
4. Verify that the new logo is displayed correctly.

Test 3: Logo Small Upload

1. Click Change Small LOGO
2. Upload a logo image
3. Crop and save the logo
   • Ensure cropping is restricted to a 1:1 or wider aspect ratio up to 1:3.
4. Verify that the new logo is displayed correctly only when screen is smaller (unless Regular logo is not uplated).

Test 4: Only one logo uploaded

1. If only a regular logo or only a smaller logo is uploaded, that logo will be applied to both wide and mobile views (test this by resizing the screen or zooming in).

Test 5: Logo Removal

1. Click Change LOGO
2. Click Remove Logo
3. Confirm that the default logo reappears.

[balmas]

Some problems noted during testing (Tested on Chrome Version 132.0.6834.160 (Official Build) (arm64))

1. After uploading a logo, then clicking save, it returns to the upload photo page, with the error "The form did not contain a 'datafile' field." The changes made on the branding page are still applied and the logo is updated, but the only way to leave the page is to click "cancel"
2. the changes seem to apply automatically most of the time. This is not true when you hit "Reset" color settings, but in most other cases, the changes apply whether or not you click Save
3. If I load a small logo but not a large logo it uses the small logo as the large logo (maybe this is intended I'm not sure)
4. Site Name looks like it's used as the html page title but it doesn't appear anywhere else
5. The copyright text doesn't get updated for any theme (it always just reverts back to the default)
6. The primary color selections are a little confusing. Changing lighter doesn't change the others, but change base does. This makes sense to some degree, but it might be better to list base first.
7. None of the changes seem to impact the Wilma theme, although they do impact the others
8. Link color doesn't seem to impact the tenderfoot theme
9. Generally, there probably needs to be some help text to explain what changing primary color affects, what changing secondary color effects,
10. When you first load the site information page, both "hide advanced color settings" and "show advanced color settings" links are present

[balmas]

see comments at #4040 (comment)

[balmas]

@milospp I'm having the same problem testing this as I am with #4039 . I use docker to test VIVO and I think the problem is that @litvinovg fix for #3034 is present in the the accompanying Vitro PR for this but not here. I tried cherry-picking the fixes into VIVO, but then ran into other problems with the Docker build. I need a clean build to test.

[litvinovg]

What does the themePrimaryColorLighter != "null" check should do?
maybe use ?has_content instead of two checks ?

[milospp]

Yes, ?has_content is a much cleaner solution. I replaced this in the code

[litvinovg]

I would use ?has_content to check that variable exists, not null and not empty

[milospp]

Replaced, thanks for the suggestions

[balmas]

I am still struggling to get this branch working for testing. Maybe rebasing from main would help.

[balmas]

@milospp I'm still getting a vitro app rather than a vivo one when I build this branch for running in Docker (using the installer/example-settings.xml) Is there a different settings file I should be using for the build?

[balmas]

Ok, starting with a completely clean environment, all my docker images purged, I was finally able to get a vivo war file built out of this branch to load vivo correctly in Docker. So that's the good news.

I did run into some problems with the functionality.

All testing is on Apple M3 Pro Sonoma 14.7.4

(1) In Firefox (138.0.3 (aarch64)) the only way I can get the branding widget to appear is if I switch themes, click on the link to get the little popup that tells me to hit save first to appear, then click save. Any other sequence fails to do anything:

https://www.awesomescreenshot.com/video/39921799?key=b598235073d45c32311257088db8c04c

There are no errors in the developer console in either browser when the widget fails to display. The feature is mostly unusable in Firefox because of this.

This does not happen in either Chrome or Safari.

(2) Uploading a logo fails because the URL to which it’s being posted has a hardcoded path element, vivo, and when running from the root, the POST fails with a 400 error (see attached screenshot)

(3) Sometimes changes made in the branding widget don’t seem to take hold. It’s hard to reproduce this reliably — It seems to happen after multiple edits to the colors. See video at https://www.awesomescreenshot.com/video/39922335?key=9b44cbc951330b7b5eb94ce311a6eb21 for an example

(4) the branding widget disappears on the Capability Map tab
See video
https://www.awesomescreenshot.com/video/39922383?key=3a2849920f93e6c77ec543c2cc385620

(5) the way the primary colors selector works is still a little hard to understand from the user perspective. If I choose the base color in the middle all three colors change, whereas if I choose the lighter or darker color (top or bottom) it doesn’t affect the others. This makes sense if I know the middle color the base color but it isn’t identified as such in the display. I think it would be better to put the base color on the top and label the three boxes so that the user can understand what is happening.

(6) When switching themes, the prior theme customizations are applied in the display while the theme-specific brand shows up in the branding widget. You have to save the changes in the widget for the new theme’s style to be applied. See video https://www.awesomescreenshot.com/video/39923187?key=67003a1aa1d65aad887ba89212437a4d

(7) there is no way to change the the color of the text and backgrounds in the browse-by navigation menu at document.querySelector("#browse-by > nav")

(8) the branding widget also disappears on the editing displays. See video
https://www.awesomescreenshot.com/video/39923049?key=dcee246f859179814c4933316483268b

[milospp]

Ok, starting with a completely clean environment, all my docker images purged, I was finally able to get a vivo war file built out of this branch to load vivo correctly in Docker. So that's the good news.

I did run into some problems with the functionality.

All testing is on Apple M3 Pro Sonoma 14.7.4

(1) In Firefox (138.0.3 (aarch64)) the only way I can get the branding widget to appear is if I switch themes, click on the link to get the little popup that tells me to hit save first to appear, then click save. Any other sequence fails to do anything:

https://www.awesomescreenshot.com/video/39921799?key=b598235073d45c32311257088db8c04c

There are no errors in the developer console in either browser when the widget fails to display. The feature is mostly unusable in Firefox because of this.

This does not happen in either Chrome or Safari.

(2) Uploading a logo fails because the URL to which it’s being posted has a hardcoded path element, vivo, and when running from the root, the POST fails with a 400 error (see attached screenshot)

(3) Sometimes changes made in the branding widget don’t seem to take hold. It’s hard to reproduce this reliably — It seems to happen after multiple edits to the colors. See video at https://www.awesomescreenshot.com/video/39922335?key=9b44cbc951330b7b5eb94ce311a6eb21 for an example

(4) the branding widget disappears on the Capability Map tab See video https://www.awesomescreenshot.com/video/39922383?key=3a2849920f93e6c77ec543c2cc385620

(5) the way the primary colors selector works is still a little hard to understand from the user perspective. If I choose the base color in the middle all three colors change, whereas if I choose the lighter or darker color (top or bottom) it doesn’t affect the others. This makes sense if I know the middle color the base color but it isn’t identified as such in the display. I think it would be better to put the base color on the top and label the three boxes so that the user can understand what is happening.

(6) When switching themes, the prior theme customizations are applied in the display while the theme-specific brand shows up in the branding widget. You have to save the changes in the widget for the new theme’s style to be applied. See video https://www.awesomescreenshot.com/video/39923187?key=67003a1aa1d65aad887ba89212437a4d

(7) there is no way to change the the color of the text and backgrounds in the browse-by navigation menu at document.querySelector("#browse-by > nav")

(8) the branding widget also disappears on the editing displays. See video https://www.awesomescreenshot.com/video/39923049?key=dcee246f859179814c4933316483268b

1. I could reproduce this only when my browser cached old brandingColors.js, so I just hard reload and removed cache (firefox, chrome

2. Fixed this (hardcoded for debug purposes and forgot...)

3. It only happened on the primary lighter color, and I fixed this. Note: There is 3 primary color (lighter, base, darker) When changing base color, lighter and darker update automatically, not sure if this is confusing sometime... Should we keep this functionality?

4. Fixed (Problems with relative paths...)

5. I removed border from secondary shades in primary colors

Also this functionality will work only with default colors, if user manually tweak lighter color it will not overide his choice (unless he reset color)

6. Fixed, but unsure if solution is good practice (explained in the next comment)

7. Linked those colors to be customisable

8. Fixed in 4

[milospp]

brandingStyles are stored in cache, which needs to be updated whenever the theme changes.
To achieve this, I had to add an if statement inside a generic function, which feels suboptimal.

Does anyone know of a better way to handle updates on theme change?

/api/src/main/java/edu/cornell/mannlib/vedit/controller/OperationController.java

            if (newObj instanceof ApplicationBean) {
                SiteBrandingController.updatethemeBrandingCache(((ApplicationBean) newObj).getThemeDir());
            }

This resolves Bridget's bullet 6.

[balmas]

Regarding (1) the firefox issue - I have tried removing my cached data, running in incognito mode, and cannot get this to work no matter what I do. Here's the error I see in the console - it seems to have trouble loading the theme-config.json, I have verified that I can load it manually (e.g. at http://localhost:8080/themes/wilma/theme-config.json) and it clearly is there.
I tried catching it through debugging statements in the developer console, but it gets lost at line 116 .

If others are able to get this to work in Firefox, I guess we could assume it is an odd problem with my environment and move on, but it would be good to have at least a couple of people check that.

All of the other problems appear fixed

Regarding the solution for (6), switching themes, I agree that the solution you implemented isn't ideal. I don't have any other good ideas unfortunately. But I also don't think this is a critical issue, since it doesn't really seem to be a very likely use case anyway. It might be better to just document the behavior than to insert that cache clearing code there.

I would like at least one other person to verify that the functionality works as it should in Firefox before I approve the PR.

[milospp]

Regarding (1) the firefox issue - I have tried removing my cached data, running in incognito mode, and cannot get this to work no matter what I do. Here's the error I see in the console - it seems to have trouble loading the theme-config.json, I have verified that I can load it manually (e.g. at http://localhost:8080/themes/wilma/theme-config.json) and it clearly is there. I tried catching it through debugging statements in the developer console, but it gets lost at line 116 .

If others are able to get this to work in Firefox, I guess we could assume it is an odd problem with my environment and move on, but it would be good to have at least a couple of people check that.

All of the other problems appear fixed

Regarding the solution for (6), switching themes, I agree that the solution you implemented isn't ideal. I don't have any other good ideas unfortunately. But I also don't think this is a critical issue, since it doesn't really seem to be a very likely use case anyway. It might be better to just document the behavior than to insert that cache clearing code there.

I would like at least one other person to verify that the functionality works as it should in Firefox before I approve the PR.

I was able to reproduce this bug in Firefox and believe I’ve resolved it. Could you please validate it again? Apologies for the inconvenience, and thank you!

[balmas]

Ok, getting closer :-). the fix does address the problem with the branding widget not displaying in Firefox. I have found 2 additional issues, one specific to Firefox, and one which was probably introduced by a recent change. Continuing with previous numbering to avoid confusion.

9. Firefox only - after selecting a color from the popup selector, if you don't explicitly close the color selector popup, and then click submit or cancel, the popup remains in the screen. And in the case of clicking Submit, your changes are not saved. And in the case of clicking Cancel, you don't get the same popup you do in the other browsers to confirm your changs won't be saved (it may be appearing but too quickly to be useful). See videos:
   https://www.awesomescreenshot.com/video/40130307?key=e1468bb8f2f41a16602a868dca09f66c
   https://www.awesomescreenshot.com/video/40130708?key=07a9075ead5753a00bc25f29385922ad

10. All browsers - the selection of the primary base color now only updates lighter and darker colors automatically with the first selection. Subsequent changes to the primary base color do not update lighter and darker. I think that was probably a result of the fix to persist subsequent changes to lighter and darker colors. I think the simplest approach here might be to only allow changes of the primary color and now allow the user to select different lighter and darker variations of it. My only concern about that is whether we can be sure the automatic choices obey accessibility guidelines.
    https://www.awesomescreenshot.com/video/40130960?key=77704d0ac2427c1baa51781d1c56295c

[milospp]

Fixed

9.1 Fixed alert message

9.2: Added a fallback save mechanism:
Users can now click Submit without first closing the color picker or editor. The changes will still be saved..

Note (macOS): The native color picker will remain open after saving due to OS behavior.

9.3 Addressed Firefox color picker limitations:
Firefox uses the native OS color picker, which behaves differently across platforms:

On Windows:

Mac:

Linux (I think):

Platform behavior summary:
On Windows, the color picker blocks interaction with the browser until it’s closed.
On macOS, users can interact with the browser even while the color picker remains open:
Also I found if a second color picker is opened without closing the first, the original disappears and becomes non-interactive (https://www.awesomescreenshot.com/video/40160102?key=8bc422f983f3704363fb8873bb272caf).

These behaviors cannot be handled with JavaScript, as the native picker opens in a separate OS-level window.
If the user does not close it, I cannot.
Creating a fully custom HTML color picker would be required for full control, but this is likely overkill for the intended functionality.

---

10. This behavior is intentional and was introduced in my previous update (see point 5).

This functionality only applies when using the default color settings. If the user manually edits the lighter color, their choice is preserved and won't be overridden unless they explicitly reset it.

Explanation:

• When the user edits the primary (emphasized) base color, both lighter and darker variants are automatically adjusted.
• If the user manually modifies either the lighter or darker color, that specific color becomes "locked" and is no longer updated automatically.
• After saving changes (with a modified primary color), further edits to the base color will no longer affect the lighter or darker variants—unless the user clicks "Reset Color," which removes the lock.

https://www.awesomescreenshot.com/video/40160534?key=3f83734eb8794f9479f7f70b5638be99

If you have any suggestions or concerns about this behavior, feel free to share them!

[balmas]

Re (10) since we can't distinguish easily between a user actively setting the lighter/darker color and it being automatically set for them by choosing a base color, there isn't a great solution here in IMHO. Most people will be able to figure out if they click Reset they can start over with the colors so I guess I'm fine with what you have coded. It could be better but it could also be worse.

Re (9) I think your fix to ensure the changes are saved or canceled as appropriate is also good enough for now. It's definitely not worth writing our own color picker at this point.

I will add my approval for this PR now (and the accompanying Vitro PR which is really where I should probably have been adding all of these comments..)

[milospp]

@balmas

Regarding topic 10, maybe we can explicitly show the state of color input.
For example:

or:

[balmas]

@milospp yes that’s a good idea. I like the 3rd option you have there the best. With the link displayed vertically between the base and darker color.

[milospp]

Implemented chain icons

Video

[balmas]

I think this is working pretty well right now. There are still a few elements that don't get changed with the branding (e.g. the tab background colors and the reset button on the Capability Map page), but frankly it's probably good enough for now.

I also noticed that in Chrome at least when you upload new logos you have to clear your browser cache for them to display.

Tested in Chrome, Firefox and Safari.

[milospp]

I think this is working pretty well right now. There are still a few elements that don't get changed with the branding (e.g. the tab background colors and the reset button on the Capability Map page), but frankly it's probably good enough for now.

I also noticed that in Chrome at least when you upload new logos you have to clear your browser cache for them to display.

Tested in Chrome, Firefox and Safari.

The Reset button on the Capability Map page is styled in red to represent a "danger" action. This color should always remain red and must not be overridden by primary, secondary, or accent colors. If someone wants to change it, a CSS update will be required.
I’d suggest leaving it as it is, but I’m open to suggestions if you think otherwise.

[milospp]

Regarding the background tab color: it currently uses a very light shade of the primary color.

Light shade components examples:

To make this customizable, it would be necessary to add an additional color picker specifically for this light shade, next to the existing primary color pickers.

Possible approach:

Do you think I should add this functionality as well?

[balmas]

I think we should just leave this as-is. Thank you for the explanations @milospp . No further requests for changes from me.

[litvinovg]

Doesn't work for me for some reason.

[litvinovg]

I see 404 errors while requesting theme-config.json and cssUploadUtils.js

[milospp]

Can you explain in detail when exactly this happened? Have you tried with another browser?

I recently changed the configuration structure stored in localStorage. If there are old values, they may be causing the issue. To handle this, I added a try–catch block that invalidates the config if the script fails to load.

[litvinovg]

When I click on "Change theme branding colors" nothing is happening and I see errors in browser console.
I tried Firefox and Chromium.
Error:
GET http://127.0.0.1:8080/vivo-main/themes/wilma/theme-config.json 404 (Not Found)

[milospp]

Can you check if you have that file in the build target location:
apache-tomcat-folder/webapps/vivo-main/themes/wilma/theme-config.json

During build, it should be copied from:
webapp/src/main/webapp/themes/wilma/theme-config.json

[litvinovg]

Can you check if you have that file in the build target location: apache-tomcat-folder/webapps/vivo-main/themes/wilma/theme-config.json

During build, it should be copied from: webapp/src/main/webapp/themes/wilma/theme-config.json

You are right, VIVO part wasn't deployed correctly. Thanks!

[litvinovg]

@milospp Could you take a look why logo's aren't displayed on any theme but Nemo?

[litvinovg]

Logo appears on tenderfoot and wilma.
One other thing I noticed is that uploading a logo with cyrillic letters in file name doesn't work. I tried attach the same file to individual and it works for some reason.
upload_image_error.txt