XWIKI-22602: Provide a UI to easily customize the logo alternative text from the colorTheme #4517

Sereza7 · 2025-08-28T14:12:42Z

Jira URL

https://jira.xwiki.org/browse/XWIKI-22602

Changes

Description

Updated the flamingo theme class to add a text alternative
Updated the theme editor
Used the new variable in the template (default is the value used previously)

Clarifications

Note that AFAIK this has no impact for sighted users. When hovering the picture, since it's part of the anchor with a title, the title of the anchor is shown ("Home"). However it's useful information for screen reader users and any assistive tech users :)
I just took the first unused number for the logo-description field of the theme class. This means that in the class editor it's far from the logo field, but since this class has a custom editor it doesn't matter much. I'd rather do that than increment the numbers of all the fields after logo...

Screenshots & Video

Here is a view of the generated DOM with the changes applied and the value Organization Name set as the logo description:

We can see that the tooltip on hover just displays "Home", but the image has the proper text alternative.

Executed Tests

Built changes successfully with mvn clean install -f xwiki-platform-core/xwiki-platform-flamingo/xwiki-platform-flamingo-skin/xwiki-platform-flamingo-skin-resources -Pquality and mvn clean install -f xwiki-platform-core/xwiki-platform-flamingo/xwiki-platform-flamingo-theme/xwiki-platform-flamingo-theme-ui -Pquality
Tested the change on my local instance, it worked as expected (see above).

Expected merging strategy

Prefers squash: Yes
Backport on branches:
- None, this is a change to a pretty sensitive class.

…xt from the colorTheme * Updated the flamingo theme class to add a text alternative * Updated the theme editor * Used the new variable in the template (default is the value used previously)

…xt from the colorTheme * Changed the prettyName to fit with other prettyNames in the ThemeClass

michitux

Thank you very much! I think in general this is a great feature, my primary complaint is that it is probably non-obvious for admins where this value is used and how it should be set.

...-theme/xwiki-platform-flamingo-theme-ui/src/main/resources/FlamingoThemesCode/ThemeClass.xml

...-theme/xwiki-platform-flamingo-theme-ui/src/main/resources/FlamingoThemesCode/ThemeSheet.xml

…xt from the colorTheme * Updated the object number

…xt from the colorTheme * Added the hint on the logo-description field

michitux · 2025-09-04T14:47:03Z

...-theme/xwiki-platform-flamingo-theme-ui/src/main/resources/FlamingoThemesCode/ThemeSheet.xml

@@ -745,6 +754,12 @@ require(['jquery', 'xwiki-l10n!xwiki-flamingo-theme-messages', 'bootstrap'], fun

 #iframe {
  height: 400px;
+}
+
+.xHint {


Would be nice if we didn't need that. Putting the xform class on any parent element wasn't an option/would break too much?

According to https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/VerticalForms/ , we should put it on the parent form tag.

I tested quickly in the inspector and it seems like it overrides the custom boldness of field names:

Yeah, probably not good to perform this change now. Maybe just add a comment in the CSS that this should be refactored to properly use the vertical forms standard (currently, it's missing the wrapping definition list).

Looking at this again, I just noticed that this selector is very broad. Please scope this selector to really only affect the color theme editing form.

Since this is a On demand only style sheet used only in this context, I figured it was okay. Note that extension.css has a similarly very wide selector for the class:

xwiki-platform/xwiki-platform-core/xwiki-platform-web/xwiki-platform-web-war/src/main/webapp/resources/uicomponents/extension/extension.css

Lines 443 to 447 in c91ee94

.xHint {

color: $theme.textSecondaryColor;

font-size: smaller;

margin: 0.3em 0;

}

I increased specificity in 1f101d5 👍

These kinds of wide selectors tend to create problems when other UI elements use the same class. Imagine a panel containing a form with a hint. I remember fixing a similar issue with the quick search that was influenced by some other CSS (but I can't find the Jira issue anymore).

michitux · 2025-09-04T14:51:39Z

...heme/xwiki-platform-flamingo-theme-ui/src/main/resources/FlamingoThemesCode/Translations.xml

@@ -108,6 +108,7 @@ platform.flamingo.themes.defaultvalue=Default
 platform.flamingo.themes.lessCode.description=In this field, you can directly write LESS code which will be added into the skin.
 platform.flamingo.themes.local=Local
 platform.flamingo.themes.global=Global
+FlamingoThemesCode.ThemeClass_logo-description.hint=Alternative text to the logo. It should describe the logo's meaning. Default: "Logo of the wiki"


I would add a comment above this to mention the other translation key with which the default value needs to be synchronized.

I added the mention of the translation inside the hint itself, from what you described in your other comment it made more sense.

Added in 913ce37 👍

michitux · 2025-09-04T14:53:47Z

Seeing the translation with the default value mentioned, I'm wondering something: in a multilingual wiki, shouldn't it be possible to localize the description of the logo? In theory, actually, also the logo itself should be localized (at least some organizations include a slogan in their logo that is translated in other languages)…

…xt from the colorTheme * Updated the translation to mention the localized value.

Sereza7 · 2025-09-08T08:25:27Z

Seeing the translation with the default value mentioned, I'm wondering something: in a multilingual wiki, shouldn't it be possible to localize the description of the logo?

I added info in the hint to make it a bit clearer that by using this field, the user is losing on the default localization. In a multilingual wiki, it's still possible to localize the description of the logo, but instead of filling up this field, the user needs to update all the translations.

michitux

Thank you very much for the changes. Overall, this looks good to me, just two last comments.

...heme/xwiki-platform-flamingo-theme-ui/src/main/resources/FlamingoThemesCode/Translations.xml

michitux · 2025-09-08T09:26:02Z

...-theme/xwiki-platform-flamingo-theme-ui/src/main/resources/FlamingoThemesCode/ThemeSheet.xml

@@ -745,6 +754,12 @@ require(['jquery', 'xwiki-l10n!xwiki-flamingo-theme-messages', 'bootstrap'], fun

 #iframe {
  height: 400px;
+}
+
+.xHint {


Yeah, probably not good to perform this change now. Maybe just add a comment in the CSS that this should be refactored to properly use the vertical forms standard (currently, it's missing the wrapping definition list).

…xt from the colorTheme * Added a comment for further improvements.

Sereza7 · 2025-09-09T08:31:04Z

Yeah, probably not good to perform this change now. Maybe just add a comment in the CSS that this should be refactored to properly use the vertical forms standard (currently, it's missing the wrapping definition list).

Done in 5f1ab3c 👍

…xt from the colorTheme * Increased specificity of the added styles

…xt from the colorTheme * Replaced curved quote in the translation with a double quote.

Sereza7 added 2 commits August 28, 2025 15:38

XWIKI-22602: Provide a UI to easily customize the logo alternative te…

7f8fdac

…xt from the colorTheme * Updated the flamingo theme class to add a text alternative * Updated the theme editor * Used the new variable in the template (default is the value used previously)

XWIKI-22602: Provide a UI to easily customize the logo alternative te…

7e287d8

…xt from the colorTheme * Changed the prettyName to fit with other prettyNames in the ThemeClass

Sereza7 assigned michitux Sep 2, 2025

Sereza7 requested a review from michitux September 2, 2025 08:07

michitux requested changes Sep 3, 2025

View reviewed changes

...-theme/xwiki-platform-flamingo-theme-ui/src/main/resources/FlamingoThemesCode/ThemeClass.xml Outdated Show resolved Hide resolved

...-theme/xwiki-platform-flamingo-theme-ui/src/main/resources/FlamingoThemesCode/ThemeSheet.xml Show resolved Hide resolved

Sereza7 added 2 commits September 4, 2025 13:36

XWIKI-22602: Provide a UI to easily customize the logo alternative te…

d2bf894

…xt from the colorTheme * Updated the object number

XWIKI-22602: Provide a UI to easily customize the logo alternative te…

28b4eeb

…xt from the colorTheme * Added the hint on the logo-description field

Sereza7 requested a review from michitux September 4, 2025 14:44

michitux reviewed Sep 4, 2025

View reviewed changes

XWIKI-22602: Provide a UI to easily customize the logo alternative te…

913ce37

…xt from the colorTheme * Updated the translation to mention the localized value.

michitux requested changes Sep 8, 2025

View reviewed changes

XWIKI-22602: Provide a UI to easily customize the logo alternative te…

5f1ab3c

…xt from the colorTheme * Added a comment for further improvements.

Sereza7 added 2 commits September 9, 2025 11:52

XWIKI-22602: Provide a UI to easily customize the logo alternative te…

1f101d5

…xt from the colorTheme * Increased specificity of the added styles

XWIKI-22602: Provide a UI to easily customize the logo alternative te…

28ae8fe

…xt from the colorTheme * Replaced curved quote in the translation with a double quote.

michitux approved these changes Sep 9, 2025

View reviewed changes

michitux merged commit 23ce728 into xwiki:master Sep 9, 2025
2 checks passed

	.xHint {
	color: $theme.textSecondaryColor;
	font-size: smaller;
	margin: 0.3em 0;
	}

Uh oh!

XWIKI-22602: Provide a UI to easily customize the logo alternative text from the colorTheme #4517

XWIKI-22602: Provide a UI to easily customize the logo alternative text from the colorTheme #4517

Uh oh!

Conversation

Sereza7 commented Aug 28, 2025

Jira URL

Changes

Description

Clarifications

Screenshots & Video

Executed Tests

Expected merging strategy

Uh oh!

michitux left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michitux commented Sep 4, 2025

Uh oh!

Sereza7 commented Sep 8, 2025

Uh oh!

michitux left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sereza7 commented Sep 9, 2025

Uh oh!

Uh oh!

Uh oh!