Tag macros contrib repo

Hi everyone,

I would like to contribute two new contrib extensions:

  • taggedpages, which display a list of pages matching the given tag
  • a modified version of the standard tagcloud macro, that allow to limit the number of tags in the cloud (a contrib extension would allow to easily deploy this modified tagcloud macro to older xwiki instances)

As both are related to tags, we were wondering with @lucaa if it was a good idea to regroup them under the same git repository, so that we would have a centralized place for tags utility macros. Do you think it would be a good idea? (and what would be the name convention for the repository in that case? Would something like macros-tag work?)

Could you create the appropriate repo for those macro? Also, we are not sure whether we would need a jira project for this.


Hi Clement,

Great! Some thoughts below.

This looks a bit similar to https://extensions.xwiki.org/xwiki/bin/view/Extension/Tag%20Application#HViewPagesForaTag. Maybe, once we have this macro, it could be reused there. How do you plan to handle scalability (lots of pages matching a tag)? What UI are you planning (a list with a “more…” link at the bottom, a tree view, a LiveData table, etc)?

I guess the repo name would be macro-taggedpages?

Even if you do it as a contrib extension for now, it would be great if you could contribute your changes back to the tagcloud macro in XWiki platform :slight_smile: And then maybe later deprecate and attic-ify the contrib repo.

What would be the macro name? {{extendedtagcloud/}} ?

I feel it’s slightly better as 2 repos because they may not have the same lifespan (and possibly not the same release cycle either).

We always need jira projects :slight_smile: This is needed to track the work and have release notes, but also for users to report problems or improvements.

Waiting for your confirmation on the 2 repo names before I create them. Also waiting a bit to see if other committers have other ideas.


How do you plan to handle scalability (lots of pages matching a tag)? What UI are you planning…

For now the design is very simple, just output the list of pages matching the given tag (and under a given space) inside a <ul> element. There is a “limit” parameter to limit the number of pages displayed, but no “more” button at the bottom.

I guess the repo name would be macro-taggedpages?


Even if you do it as a contrib extension for now, it would be great if you could contribute your changes back to the tagcloud macro in XWiki platform

For sure, this is already planned! :slight_smile:

What would be the macro name? {{extendedtagcloud/}} ?

It depends, what do you think is best? Should I create a separate macro with a different name, (and then we use this custom one on instances), or should I use the same name than the tagcloud macro and prevent installing this extension on instances more recent than the product version where the updated tagcloud macro was introduced?

I feel it’s slightly better as 2 repos

Let’s go for two separate repos then!

actually, there is a bit of a danger here, let’s think it through.

If we use another macro, {{extendedtagcloud}} , then people will start using it, let’s say on version 14.4.x, in their wiki pages.
Then, they will upgrade to a version of XWiki, let’s call it XWiki 15, which sports the improved {{tagcloud}} macro with limits. Moreover, at this point {{extendedtagcloud}} is not compatible anymore with their instance (because we want to prevent people from redundantly installing it on a version of XWiki that already has a better tagcloud macro).
At this point, all the content that they have already created that uses the {{extendedtagcloud}} macro is not working anymore and the only way to fix it is to manually go and update those pages one by one. Or by using a velocity / groovy script with a regex in it. And now we have 2 problems .

There are 2 alternatives to this:

  • not make a new macro {{extendedtagcloud}}, but just provide an extension that dangerously overwrites the standard {{tagcloud}} macro and adds a new, optional, limit parameter to it, while keeping all the rest as is. On 14.4.x people install it, existing tagclouds still work properly and they can add new tagclouds with limits. Upon upgrade the extension becomes invalid, they uninstall it and their tagclouds with limits continue working just fine because the macro exists and new param is now provided by the platform.
  • we do make a new different macro {{extendedtagcloud}}, but then:
    • indeed, the extension would be more elegant because it wouldn’t overwrite a standard macro;
    • there will be confusion for normal users as to why there are 2 of them and which one to use. Knowing that one does whatever the other does and something more;
    • we’d then keep the name {{extendedtagcloud}} by maintaining this extension as a legacy thing and not make it invalid on newer versions of XWiki when the tagcloud would be fixed, in order to preserve the working content. As there may be no end to the time of maintenance of this, we would be creating an obligation to kind of keep this extension even if we improved the platform.

Despite overwriting the macro page from a platform application in a contrib extension (alternative 1 above) being an “ugly hack”, I like it more in terms of what it gives, especially if we’re this convinced that these improvements should become part of the standard platform tag application.


I’ve just created a jira issue and a PR for this! :slightly_smiling_face:

1 Like

WDYM by not compatible? How do you enforce that? And why would the macro not work anymore?

Why does it become invalid? How do we do that? AFAIR the minimal xwiki version will be lower than the version they upgrade to and thus should be valid.

For me the problem is that the contrib macro will continue to override the platform one (since it’ll have a higher component priority), and thus if the platform macro is improved, it won’t be used until they voluntarily uninstall the contrib macro.

Yes. Note that macros can be hidden nowadays (but that’s 14.8-rc-1+).

I think I agree. I’m trying to remember the issues we had with a contrib macro overriding a platform one in the past but I can’t remember anything right now except what I wrote above about the need for the user to voluntarily uninstall the contrib macro at some point.


With an upper bound on the version of its platform dependency (i’m pretty sure this is possible but maybe I am wrong). Its platform dependency would be the tagcloud extension.

The macro could work, just that the extension will not be valid anymore because of that enforced dependency version.

As explained above, the idea is that that extension will have a maximal xwiki version (as far as I know it’s possible, but maybe I am wrong), in order to prevent it from being installed on an XWiki version that already has the fix in the standard tagcloud extension.

As far as I understand this new feature from here https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/14.8RC1/#HMiscellaneous-1 , this would require a change of the macro itself in order to hide it, so we would need to overwrite the standard {{tagcloud}} macro anyway in order to make it hidden. If we’re fine with overwriting macros, I prefer to overwrite it with some new parameter.

which is why I thought about this upper bound thing, to make it both uninstallable on higher versions of xwiki and invalid if people upgrade…

ok I’m not aware of this feature (never used it).

It’s configurable through config in xwiki.properties.

well, that documentation talks about hiding entire categories of macros.
We cannot hide the whole “Content” category (which is the category of the tagcloud macro). So in order to hide the default tagcloud we’d need to either assign it a hidden category or a new category that we’d then hide in xwiki.properties.

Unless there is another configuration that allows to hide macros individually, in which case you were talking about a different feature than the one I linked to…

I just checked, there is a configuration in xwiki.properties that allows to overwrite a macro category, and that one is since 2.0M3 . So I guess that even before 14.8-rc-1 it would be possible to hide tagcloud by assigning it a category that is hidden by default (not sure in which version we started hiding macro categories)…

yes that’s the one I’m referring to, but that won’t help with XWiki < 14.8-rc-1 since the feature to hide some category is new in 14.8-rc-1 (see https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/14.8RC1/#HMiscellaneous-1).

Maybe I misread that text or maybe that is written in a misleading way, but it implies that before 14.8-rc-1 the hidden categories feature existed but it was hardcoded to “Internal” and “Deprecated” (“previously hard-coded to Internal and Deprecated”), and that the only thing that is new starting with 14.8-rc-1 is the fact that those categories can now be configured.
So, based on that, I expect that if you update the tagcloud category to “Deprecated”, it would be hidden, even before 14.8-rc-1 (but I don’t know starting with what version, I would need to check when we started to hardcode the hiding of the 2 categories).

I didn’t misread, it was not misleading, deprecated and internal macros are hidden since 9.7-rc-1 : https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/9.7RC1/#HDeprecatedandInternalMacrosHiddenbyDefault .

Yes you’re right, except on one point. In the past we were not really hiding categories. As you can see in the screenshot you can still see the deprecated category for example. With the new feature, users cannot select macros in the hidden categories.


well, that’s not what https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/14.8RC1/#HMiscellaneous-1 actually says - I mean it doesn’t mention any change in the functional effect of hidden categories; moreover this new functional consequence of hidden categories is not described anywhere in the release notes of 14.8-rc-1.

Yes, I’ve checked the various release notes at https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/# and there’s no mention of that. It’s likely that @mleduc has forgotten it and that we need to update https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/14.8RC1/Entry008/ to indicate it.

Since nobody else has commented I’ll go ahead and create 2 contrib repos:

  • macro-taggedpages. It’ll contain a {{taggedpages}} macro.
  • macro-extendedtagcloud (with the goal of moving it to xwiki-attic in the future). It’ll contain a {{tagcloud}} macro with a higher priority than the default, in order to overwrite the default platform macro of the same name (i.e. < 1000, e.g. 900).

I’ll also create the jira projects.


1 Like


Please add .gitignore to these repos, license files, README.md as mentioned on https://contrib.xwiki.org/xwiki/bin/view/Main/WebHome#HREADME.mdTemplate


1 Like

Thanks @vmassol!

In 14.8 the list of hidden categories becomes configurable, and has been temporarily hard-coded to Deprecated + Internal since 14.6.
I’ve updated https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/14.6RC1/#HCkeditorMacroDialogfiltersbycategories accordingly.

Sorry about that miss.