Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

XWIKI-22165: Home page icons do not have a text alternative #3123

Open
wants to merge 11 commits into
base: master
Choose a base branch
from
Open

XWIKI-22165: Home page icons do not have a text alternative #3123

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
9fc3b59
XWIKI-22165: Home page icons do not have a text alternative
Sereza7 May 17, 2024
fb87604
Merge branch 'xwiki:master' into XWIKI-22165
Sereza7 May 24, 2024
f1b8e50
XWIKI-22165: Home page icons do not have a text alternative
Sereza7 May 24, 2024
10f576c
XWIKI-22165: Home page icons do not have a text alternative
Sereza7 Sep 6, 2024
df42d34
Merge branch 'master' into XWIKI-22165
Sereza7 Sep 6, 2024
2f71bec
XWIKI-22165: Home page icons do not have a text alternative
Sereza7 Sep 11, 2024
a0815ef
Merge branch 'xwiki:master' into XWIKI-22165
Sereza7 Sep 11, 2024
7d12a73
XWIKI-22165: Home page icons do not have a text alternative
Sereza7 Sep 11, 2024
6ae4ff0
Merge branch 'xwiki:master' into XWIKI-22165
Sereza7 Nov 27, 2024
51edb3b
XWIKI-22165: Home page icons do not have a text alternative
Sereza7 Nov 27, 2024
ac286c2
XWIKI-22165: Home page icons do not have a text alternative
Sereza7 Jan 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions ...ki-platform-icon-macro/src/main/java/org/xwiki/icon/macro/DisplayIconMacroParameters.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,8 @@ public class DisplayIconMacroParameters

private String iconSet;

private String textAlternative;

private boolean fallback = true;

/**
Expand Down Expand Up @@ -100,4 +102,24 @@ public void setFallback(boolean fallback)
{
this.fallback = fallback;
}

/**
* @since 16.5.0RC1
Sereza7 marked this conversation as resolved.
Show resolved Hide resolved
* @return the text alternative picked for the icon
*/
public String getTextAlternative()
{
return this.textAlternative;
}

/**
* @since 16.5.0RC1
Sereza7 marked this conversation as resolved.
Show resolved Hide resolved
* @param textAlternative a text alternative for the icon
*/
@PropertyName("Text Alternative")
@PropertyDescription("A text alternative for this icon.")
public void setTextAlternative(String textAlternative)
{
this.textAlternative = textAlternative;
}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Sereza7 have you tried to build this module with the quality profile? It's an API it seems, and you're missing unstable annotations I think. And I'm surprised revapi is not complaining at all.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding methods to a class isn't breaking anything, so I wouldn't expect any errors.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, not an interface. Still missing the unstable annotations then.

Copy link
Contributor Author

@Sereza7 Sereza7 Sep 11, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the quality profile, I hit the ClassFanOutComplexity on DisplayIconMacro, working on fixing it...

Copy link
Contributor Author

@Sereza7 Sereza7 Sep 11, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added the Unstable annotation in 7d12a73 👍
Also reduced the fanout complexity by choosing to use a paragraph block instead of a FormatBlock for the text alternative. Now passes mvn clean install -f xwiki-platform-core/xwiki-platform-icon/xwiki-platform-icon-macro -Pquality successfully.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm sorry but using a paragraph block for the text alternative is not okay, you cannot nest a paragraph inside another paragraph and the icon macro needs to be usable in a paragraph.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reverted this change of block nature in 51edb3b .
Instead of this, I set some methods in their own class in order to reduce the ClassFanOutComplexity of DisplayIconMacro.

The PR with these new changes pass quality tests :)
mvn clean install -f xwiki-platform-core/xwiki-platform-icon/xwiki-platform-icon-macro -Pquality

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I went with a solution without components since those methods are quite specific and I don't think they'd need to be reused in another context.

}
13 changes: 13 additions & 0 deletions ...iki-platform-icon-macro/src/main/java/org/xwiki/icon/macro/internal/DisplayIconMacro.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
*/
package org.xwiki.icon.macro.internal;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Set;
Expand All @@ -40,8 +41,11 @@
import org.xwiki.rendering.async.internal.AbstractExecutedContentMacro;
import org.xwiki.rendering.async.internal.block.BlockAsyncRendererConfiguration;
import org.xwiki.rendering.block.Block;
import org.xwiki.rendering.block.FormatBlock;
import org.xwiki.rendering.block.ParagraphBlock;
import org.xwiki.rendering.block.WordBlock;
import org.xwiki.rendering.block.XDOM;
import org.xwiki.rendering.listener.Format;
import org.xwiki.rendering.listener.MetaData;
import org.xwiki.rendering.macro.MacroExecutionException;
import org.xwiki.rendering.syntax.Syntax;
Expand Down Expand Up @@ -142,6 +146,15 @@ public List<Block> execute(DisplayIconMacroParameters parameters, String content
throw new MacroExecutionException("Failed parsing and executing the icon.", e);
}

if (parameters.getTextAlternative() != null) {
// We complete the icon with a text alternative for screen readers.
Block textAltBlock = new FormatBlock(List.of(new WordBlock(parameters.getTextAlternative())), Format.NONE);
textAltBlock.setParameter("class", "sr-only");
ArrayList<Block> updatedList = new ArrayList<>(result);
updatedList.add(textAltBlock);
result = List.copyOf(updatedList);
}

return result;
}

Expand Down
23 changes: 23 additions & 0 deletions ...e/xwiki-platform-icon/xwiki-platform-icon-macro/src/test/resources/macrodisplayicon6.test
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
.runTransformations
.#-----------------------------------------------------
.input|xwiki/2.1
.# Verify the text alternative functionality
.#-----------------------------------------------------
{{displayIcon name="home" textAlternative="Home" /}}
.#-----------------------------------------------------
.expect|event/1.0
.#-----------------------------------------------------
beginDocument
beginMacroMarkerStandalone [displayIcon] [name=home|textAlternative=Home]
beginMetaData [[syntax]=[XWiki 2.1]]
beginParagraph
beginFormat [NONE] [[class]=[icon][data-xwiki-icon]=[homeIcon]]
onWord [i]
endFormat [NONE] [[class]=[icon][data-xwiki-icon]=[homeIcon]]
endParagraph
endMetaData [[syntax]=[XWiki 2.1]]
beginFormat [NONE] [[class]=[sr-only]]
onWord [Home]
endFormat [NONE] [[class]=[sr-only]]
endMacroMarkerStandalone [displayIcon] [name=home|textAlternative=Home]
endDocument
8 changes: 5 additions & 3 deletions ...tion-flavor/xwiki-platform-distribution-flavor-common/src/main/resources/Main/WebHome.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,13 @@ XWiki can be used as a knowledge base (support, documentation, sales, etc.), for

To make the most out of your wiki, log-in and:

Use the {{displayIcon name="pencil"/}} button above to //edit// this page and start customizing your wiki to your needs.
Use the {{displayIcon name="pencil" textAlternative="Edit"/}} button above to //edit// this page and start customizing your wiki to your needs.

Use the {{displayIcon name="add"/}} button above to //add// more pages to your wiki and create the //hierarchy// that best organizes your content.
Use the {{displayIcon name="add" textAlternative="Create"/}} button above to //add// more pages to your wiki and create the //hierarchy// that best organizes your content.

Use the {{displayIcon name="home"/}} breadcrumbs located above the title to //navigate// inside your pages. It's easy to get lost in a big wiki without them.
Use the {{displayIcon name="home" textAlternative="Home"/}} breadcrumbs located above the title to //navigate// inside your pages. It's easy to get lost in a big wiki without them.

{{html}}&lt;p class="sr-only"&gt;Those three buttons are accessible using a keyboard between the global navbar elements and the main page content.&lt;/p&gt;{{/html}}

You can also use the [[Sandbox&gt;&gt;Sandbox.WebHome]] for more demo content and generally a place to experiment with your wiki's features.

Expand Down