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.

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

XRENDERING-736: Macros info, success, warning and error are only distinguished by colors #286

Merged
merged 29 commits into from
Feb 15, 2024

Conversation

Sereza7
Copy link
Contributor

@Sereza7 Sereza7 commented Nov 8, 2023

Jira

https://jira.xwiki.org/browse/XRENDERING-736

PR Changes

  • Added the appropriate changes to the block structure of the message macro

Note

When testing on a default XWiki distribution, those icons use the Silk icon theme despite the selected color theme being Font awesome 4.

Tests

Passed successfully mvn clean install -f xwiki-rendering/xwiki-rendering-macros/xwiki-rendering-macro-message/.

21452-afterPR
Here, we can see that the icons are properly added on a sandbox page with message boxes of the four types.
However, additional style must be provided for them to look better, which will be done in a pull request for xwiki-platform.

EDIT: Updated Jira URL

Also see xwiki/xwiki-platform#2590 on xwiki-platform

…uished by colors

* Added the appropriate changes to the block structure of the message macro

Note: Those icons use the Silk icon theme.
@tmortagne
Copy link
Member

Would be great to see a screenshot of how it looks like when there is a title.

@vmassol
Copy link
Member

vmassol commented Nov 8, 2023

Thanks Lucas.

However, additional style must be provided for them to look better, which will be done in a pull request for xwiki-platform.

Don't hesitate to ask Thiago for a review (and suggestions).

} else {
// Enhance the default box with an icon in the top left.
Block defaultBox = boxFundation.get(0);
Block iconBlock = new ImageBlock(this.getIconReference(), true);
Copy link
Member

@tmortagne tmortagne Nov 8, 2023

Choose a reason for hiding this comment

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

An actual image inserted in the content does not feel like the cleanest. I would have expected the exact icon to be a CSS (so on platform side) decision based on the class (like the color).

Copy link
Contributor Author

@Sereza7 Sereza7 Nov 8, 2023

Choose a reason for hiding this comment

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

We want the icon to be accessible from a screen reader, so unfortunately we can't just add it in the :before pseudo-element of the message box.

I thought the best practice would be to add an image in it, but I think I could also just add an empty Format Block just like for the title, and somehow fill it with CSS.

However AFAIK, the various iconthemes also have various ways to represent icons in HTML, some use images, some use fonts, ... so I'm pretty sure we'd need more than CSS to solve this rendering completely.

Copy link
Contributor

Choose a reason for hiding this comment

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

We have unfortunately no way to insert icons by CSS unless I missed something. Regarding the screen reader aspect, that's easy to solve I think by adding a sr-only text. But then again, I'm not really sure that this is something we should do in rendering as sr-only is not a standard but comes from Bootstrap iirc. Imho it would be cleanest to override these macros in xwiki-platform to add proper icon HTML from the icon theme.

@Sereza7
Copy link
Contributor Author

Sereza7 commented Nov 8, 2023

Would be great to see a screenshot of how it looks like when there is a title.

21452-afterPR2

The title is not rendered when inline. The style displayed here is not final, I plan on making adjustements in some CSS files on xwiki-platform.

@Sereza7
Copy link
Contributor Author

Sereza7 commented Nov 9, 2023

Setting this PR as a draft to add a block around the title, so that it's easier to style.

…uished by colors

* Added a container for the box title

Note: These changes go beyond the context of message macros.
@Sereza7
Copy link
Contributor Author

Sereza7 commented Nov 10, 2023

Updated this PR to add a container for the box title: this is a span, with the class 'box-title'.

Here is a display of what this looks like in a XWiki HTML structure:
21452-boxTitleUpdateRendering

@Sereza7 Sereza7 marked this pull request as ready for review November 10, 2023 14:17
@@ -10,9 +10,9 @@
beginDocument
beginMacroMarkerStandalone [custombox] [] [something]
beginGroup [[class]=[box]]
beginMetaData [[non-generated-content]=[java.util.List<org.xwiki.rendering.block.Block>][parameter-name]=[title]]
Copy link
Member

Choose a reason for hiding this comment

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

Does it mean that the title is not inplace editable anymore? AFAIR those metadata blocks were there on purpose to allow direct edition.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Indeed, without this block, it's not possible to select the title for direct inplace editing. We can only change it through the message box properties.

Copy link
Contributor Author

@Sereza7 Sereza7 Nov 15, 2023

Choose a reason for hiding this comment

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

👍 Addressed in dcd57c2

21452-updatedTitleMetadata

Note that the presentation from xwiki-platform is broken when inplace editing too ^^'

Copy link
Contributor

@michitux michitux Nov 17, 2023

Choose a reason for hiding this comment

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

Shouldn't the title be a block element like <div>? I remember that we had a problem that inline elements weren't editable in CKEditor. See https://jira.xwiki.org/browse/XWIKI-17417

Copy link
Contributor Author

Choose a reason for hiding this comment

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

AFAICS this works properly with the changes proposed on xwiki-platform:

Demo video

Copy link
Contributor

Choose a reason for hiding this comment

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

Hm, yes, though our inline parsing is not really reliable so if you put something like == Big title == as title it will break WYSIWYG editing as the "corrected" HTML by the browser breaks the macro content markers.

@Sereza7 Sereza7 marked this pull request as draft November 15, 2023 09:10
…uished by colors

* Added back the metadata block
@Sereza7 Sereza7 marked this pull request as ready for review November 15, 2023 09:53
Sereza7 and others added 2 commits November 17, 2023 10:16
…stinguished by colors


* Updated list instantiation

Co-authored-by: Manuel Leduc <manuel.leduc@xwiki.com>
…uished by colors

* Added an interface and a component to handle icon providing.

Note: the default behavior is the same within xwiki-rendering, but there, xwiki-platform can override the component to allow usage of icon themes for transformations or generic icon use.
@Sereza7 Sereza7 marked this pull request as draft December 12, 2023 16:27
Sereza7 and others added 3 commits December 13, 2023 10:06
…uished by colors

* Properly use the interface to instantiate the icons
* Added a method to the interface to make sure the transformation icons work properly whatever the provider used
* Fixed the POM
@Sereza7
Copy link
Contributor Author

Sereza7 commented Dec 13, 2023

The last changes add a new API to provide icons for rendering. Previously it only supported images. Now this can be extended. This has the aadvantage of allowing support of icon themes that are not based on images, like Font Awesome :)

__
I took this opportunity to update the transformation feature, and not just the AbstractMessage, as they are both very similar.

Here is what a page rendered in XWiki 16.0-SNAPSHOT looks like with the iconTheme being Font awesome:
21452-replacingIcons-FA

…uished by colors

* Added a wrapping block for easier styling
@Sereza7
Copy link
Contributor Author

Sereza7 commented Dec 13, 2023

Added some wrapping around the title + content of the block when necessary
Most of the changes are on xwiki/xwiki-platform#2590
21452-updatedStyle-FA

@Sereza7 Sereza7 marked this pull request as ready for review December 13, 2023 18:23
…uished by colors

* Fixed the rule for wrapping children

Note: Previous conditions were overcomplicated and did not generalize well (issue when using an image without a title)
Copy link
Contributor

@michitux michitux left a comment

Choose a reason for hiding this comment

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

Thank you for updating this! I like the new approach with the icon provider. Just some details that need to be fixed. Also, please also open a rendering issue for this, or we should move the issue to rendering. It is fine to have a commit with a XRENDERING-Jira-issue in platform but not the other way around from my understanding.

The update of the icon transformation is nice, but I think it should be its own Jira issue and its own pull request or at least clearly separate commits as while I would backport the box macro to 15.10.x, I wouldn't do that for the icon transformation. The reason for this is that I'm worried that non-images might cause issues with exports. What happens if you export a document with smileys to an office format or LaTeX? I haven't tested this before so I don't know if icons were supported, but in general PNG icons should be much less of an issue than Font Awesome icons. Now I'm not saying that we need to fix this here, just something to think about in general and find a solution in XWiki 16.x.

@@ -10,9 +10,9 @@
beginDocument
beginMacroMarkerStandalone [custombox] [] [something]
beginGroup [[class]=[box]]
beginMetaData [[non-generated-content]=[java.util.List<org.xwiki.rendering.block.Block>][parameter-name]=[title]]
Copy link
Contributor

Choose a reason for hiding this comment

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

Hm, yes, though our inline parsing is not really reliable so if you put something like == Big title == as title it will break WYSIWYG editing as the "corrected" HTML by the browser breaks the macro content markers.

Comment on lines 22 to 26
import java.util.Set;
import org.xwiki.component.annotation.Component;

import javax.inject.Named;
import javax.inject.Singleton;

import org.xwiki.component.annotation.Component;
import java.util.Set;
Copy link
Contributor

Choose a reason for hiding this comment

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

This reordering does not respect our code style, see https://dev.xwiki.org/xwiki/bin/view/Community/CodeStyle/JavaCodeStyle/#HImports. Please configure your IDE to follow XWiki code style.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Addressed in 95bae64 👍

* @param iconName the name of the icon needed
* @return the block containing the icon
*/
public Block get(String iconName)
Copy link
Contributor

Choose a reason for hiding this comment

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

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Addressed in 95bae64 👍

* @version $Id$
* @since 15.10.2
*/
@Role
Copy link
Contributor

Choose a reason for hiding this comment

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

This needs to be @Unstable.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Addressed in 95bae64 👍

// Add an image block as the last block
pointer.addChild(new ImageBlock(new ResourceReference(iconName, ResourceType.ICON), true));
// Add an icon block as the last block
pointer.addChild(iconProvider.get(iconName));
Copy link
Contributor

Choose a reason for hiding this comment

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

The documentation mentions that the icon names are silk icon names. Are all silk icon names available in all icon themes? Also, I would have expected a separate Jira issue for this change.

Copy link
Contributor Author

@Sereza7 Sereza7 Jan 5, 2024

Choose a reason for hiding this comment

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

Are all silk icon names available in all icon themes?

No, but there's a fallback in the iconProvider that creates an ImageBlock like it used to be here. So even if it doesn't find the icon in the mapping, it'll put a Silk icon instead.

Also, I would have expected a separate Jira issue for this change.

This relies on the iconProvider class created in this PR, and it's a necessary change to solve XWIKI-21452 AFAIK, so I think it makes sense to leave it here.

@Singleton
public class DefaultIconProvider implements IconProvider
{
private static final List<Class> ICON_CLASS = new ArrayList<Class>(List.of(ImageBlock.class));
Copy link
Contributor

Choose a reason for hiding this comment

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

I don't think this is needed at all, but still, why are you using an ArrayList here?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Because the iconProvider can send back multiple kinds of icons. See https://github.com/xwiki/xwiki-platform/pull/2590/files#diff-8d2b165ed0bf133c701f7ce2d59119be83117a10967c9257eeb97990143ad7abR73
This one relies on the default behaviour and can send back RawBlocks and ImageBlocks.

This wouldn't be needed when implementing #286 (comment)

* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
package org.xwiki.rendering.transformation.icon;
Copy link
Contributor

Choose a reason for hiding this comment

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

I think I would put this in xwiki-rendering-api. I don't know if this opinion is shared by others, but to me this icon transformation doesn't seem very modern, and it is causing many issues (like it breaks the WYSIWYG experience as it cannot be applied in WYSIWYG) which is why I would actually prefer to just remove it/turn it into a contrib extension.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Addressed in cb8e83d 👍

@@ -41,5 +41,10 @@
<artifactId>xwiki-rendering-macro-box</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.xwiki.rendering</groupId>
<artifactId>xwiki-rendering-transformation-icon</artifactId>
Copy link
Contributor

Choose a reason for hiding this comment

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

I don't think a macro as simple as the message macro should depend on the icon transformation. But see also my comment on the IconProvider.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Addressed when moving the IconProvider to xwiki-rendering-api 👍


import javax.inject.Inject;
import java.util.Collections;
import java.util.List;
Copy link
Contributor

Choose a reason for hiding this comment

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

Wrong import order (see also below).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Addressed in 95bae64 👍

…inguished by colors

* Updated the logic for the IconTransformation parser to fit the new composite type
@Sereza7 Sereza7 marked this pull request as draft January 5, 2024 16:50
…inguished by colors

* Fixed an outdated POM
* Cleaned up code
@Sereza7
Copy link
Contributor Author

Sereza7 commented Jan 10, 2024

Also, please also open a rendering issue for this, or we should move the issue to rendering. It is fine to have a commit with a XRENDERING-Jira-issue in platform but not the other way around from my understanding.

Opened XRENDERING-736: Macros info, success, warning and error are only distinguished by colors and updated the title of this PR :)

Note:
TLDR in order to use xwiki-rendering-api, one should also build xwiki-legacy-rendering-api
It took me a while to understand how to add my xwiki-rendering-api jar to my local distribution. The first step is to build this jar, but then we need to build legacy (making sure it used the proper version of the api...) and create a symlink between the legacy package result and the one in the local distribution.

@Sereza7 Sereza7 marked this pull request as ready for review January 10, 2024 14:21
* @version $Id$
* @since 15.10.4
*/
public class IconBlock extends CompositeBlock
Copy link
Contributor

Choose a reason for hiding this comment

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

I didn't suggest introducing this as an API to be used outside the rendering transformation. Also, if you really want to make this an API, this needs to be @Unstable. To me, having an IconBlock would suggest that it somehow actually represents an icon, which is not the case here. To me, the use of this is too limited to justify having a new kind of block.

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 moved the IconBlock class in the IconProvider. This way, it's easily accessible from any class that might need it.
I still don't know if this is a correct place but this looks less wrong to me.

See 8798113

From what I understand, it becomes an unstable API, but less open ended, we have a clear context in which to use it.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Okay, I removed the IconBlock class altogether, replacing it with a static parameter to give to the icon block, in da1ab07. This has the advantage of not changing the nesting for icon blocks and not breaking the tree traversal algo that was before.

The disadvantage:

  • using this parameter name-value combination will break the tree traversal and the block will be interpreted like an icon.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

After seeing your comment at #286 (comment), I moved this parameter to the iconTransformation class and made it private.
I also updated the name of the parameter to decrease the risk of collision with another feature.
Changes in 5caf98e

* @param iconName the name of the icon needed
* @return the block containing the icon
*/
IconBlock get(String iconName);
Copy link
Contributor

Choose a reason for hiding this comment

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

I think I would have let this return a Block.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This would open the door to implementing iconProviders that would break the icon transformation feature. I think it's for the best to rely on a more precise class with minimal expectations.

Copy link
Contributor

Choose a reason for hiding this comment

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

I have the feeling you kind of misunderstood my original idea. My idea was that the icon transformation wraps whatever block the IconProvider returns inside an IconBlock, but an IconBlock class that is private to the icon transformation. That way, the icon transformation knows also that this IconBlock has exactly one child. This IconBlock class would not be used anywhere else.

Copy link
Contributor Author

@Sereza7 Sereza7 Jan 16, 2024

Choose a reason for hiding this comment

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

Thank you for your help!
I think I understand it now :)
See #286 (comment)

for (int i = 0; i < count - 1; i++) {
matchStartBlock.getParent().removeBlock(matchStartBlock.getNextSibling());
}
sourceBlock = mappingCursor.clone();
sourceBlock = mappingCursor
.getFirstBlock(AnyBlockMatcher.ANYBLOCKMATCHER, Block.Axes.DESCENDANT).clone();
Copy link
Contributor

Choose a reason for hiding this comment

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

Why are you cloning the first child of the icon block? What if the icon block has several children?

Copy link
Contributor Author

@Sereza7 Sereza7 Jan 16, 2024

Choose a reason for hiding this comment

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

The way I defined and used the IconBlock so far is that it contains only one child which is a block containing the whole icon.


After thinking about it, there's no reason to exclude other use cases where multiple blocks are given as children, possibly imposing an extra wrapping that's not needed.


After looking at the way we parse trees, it's not straigthforward to allow multiple children.


I have trouble understanding what this function does, there are a lot of abstract concepts and minimal documentation (and the recursive nature of the function does not make things simpler). With a simple test (1. make sure the default renderer behaves correctly, and 2. make sure a renderer that add a random wordBlock behaves as expected) I couldn't find out an easy change that would return the expected value for tests on both cases...
I think it's okay to assume that all the content in the Icon block is nested inside a singular block.
I'm adding a line in the definition of the IconBlock to highlight this.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Wrapping the children blocks in a composite block when they are multiple does not work either.

Copy link
Contributor

Choose a reason for hiding this comment

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

Why don't you just clone the IconBlock itself, i.e., just revert the change on this line?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Somehow it fails at transforming multiple icons one after the other:
https://up1.xwikisas.com/#6lC3HfY35P2Qv2BVGf6LKw

…inguished by colors

* Moved around the IconBlock class
…inguished by colors

* Replaced the IconBlock class with a parameter
…inguished by colors

* Moved the parameter from the IconProvider interface to the private usage of IconTransformation
…inguished by colors

* Moved the IconProvider classes to util instead of transformation
@Sereza7
Copy link
Contributor Author

Sereza7 commented Jan 17, 2024

Changes since #286 (comment) :

  • Replaced the IconBlock class that was in the API with a block parameter that's defined at the level of icon transformation (since it's only useful in there)
  • Moved around the IconProvider interface and DefaultIconProvider class to the util package instead of transformation where they were before.
  • Misc changes in the different files to fit the changes above.

Executed tests

As of the end of af1759b, I could successfully build:

  • mvn clean install -f xwiki-rendering-api
  • mvn clean install -f xwiki-rendering-transformations/xwiki-rendering-transformation-icon
  • mvn clean install -f xwiki-rendering-macros/xwiki-rendering-macro-message
  • mvn clean install -f xwiki-rendering-macros/xwiki-rendering-macro-box

which covers all the changes.

…inguished by colors

* Use a custom block to wrap icons in the icon transformation instead of
  using a parameter that would be present in the output.
@Sereza7
Copy link
Contributor Author

Sereza7 commented Jan 17, 2024

Thanks for your help Michael!
I'll rerun the builds to make sure nothing got broken and keep this topic updated :)

@michitux
Copy link
Contributor

As mentioned in the chat, the changes to the icon transformation should be separated from the changes for XRENDERING-736 as they are completely independent, they are just much easier now. The potential problem I see with this change is that export to different formats like office formats or LaTeX won't handle HTML output and thus won't display the icons anymore which could be seen as a regression. I think we need to re-think how we handle icons but regardless how we handle icons in the future, it should be possible to adjust the icon provider to the chosen solution.

…inguished by colors

* Reverted all changes on the IconTransformation

Note: adding them in a comment for XRENDERING-738 so that we can use them later if needed
@Sereza7
Copy link
Contributor Author

Sereza7 commented Jan 17, 2024

I removed all the changes to the icon transformation in a451d60. I created a ticket for this issue: https://jira.xwiki.org/browse/XRENDERING-738 and added the fix discussed here as a comment.

Additionally, after a last check, all the builds mentionned above still pass sucessfully.

Copy link
Contributor

@michitux michitux left a comment

Choose a reason for hiding this comment

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

Thank you, just a few minor suggestions for documentation update.

I fear, following the comment of @vmassol on #2775 there should be a forum proposal that details the UI change with the exact new look that was chosen before this can be merged.

@Sereza7
Copy link
Contributor Author

Sereza7 commented Jan 17, 2024

I started a forum proposal on https://forum.xwiki.org/t/updating-the-presentation-of-message-macros/13872 👍

Sereza7 and others added 3 commits January 17, 2024 16:51
…inguished by colors


* Updated `since` fields

Co-authored-by: Michael Hamann <michael@content-space.de>
…inguished by colors


* Updated `since` fields

Co-authored-by: Michael Hamann <michael@content-space.de>
…inguished by colors


* Improved javadoc

Co-authored-by: Michael Hamann <michael@content-space.de>
…inguished by colors

* Rewriting of a selector using a more straightforward syntax.

Note: It has been built with standard tests successfully and behaves the same as before for manual tests on a local distribution.
…inguished by colors

* Updated `since` annotations
@michitux michitux merged commit 35f2d28 into xwiki:master Feb 15, 2024
michitux added a commit that referenced this pull request Feb 16, 2024
…nly distinguished by colors (#286)"

This reverts commit 35f2d28.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants