Review of rendering macro categories

Hi, I checked today the list of macros we show in the WYSIWYG editor and their categories and I’ve noticed some inconsistencies:

  • Content:
    • Async macro: should it be in Development like the Cache macro?
    • Pages: could also be in Navigation
  • Development:
    • WikiMacro Content: should we move it to Internal?
    • WikiMacro Parameter: should we move it to Internal?
  • Layout:
    • Gallery: should we move it to Content, like Chart and Office Viewer?
  • Notifications:
    • Activity (legacy): either we move it to Deprecated or remove the “(legacy)” suffix
    • “Notifications XXX Preferences”: should these be in Internal? Are they useful for end users? What’s exactly their use case for the end user?
    • Notifications Filters Preferences (deprecated): should be moved to Deprecated (or Internal, see above)
  • Other:
    • User Mention: should be moved to Social

WDYT?

hmm I would indeed put the cache macro and the async macro in the same category. However, I’m not 100% sure about “development” (which IMO targets developers). Here I think they’re meant to be used by users and they’re concerning “content”.

I’d be fine with both options.

What is this macro? Is it the “documents” macro (https://extensions.xwiki.org/xwiki/bin/view/Extension/Documents%20Macro)?

Yes it could go in Navigation.

yes I agree.

Layout is more precise than Content for me. Maybe we need a new category for these? See https://developer.atlassian.com/server/confluence/including-information-in-your-macro-for-the-macro-browser/ for ideas:

  • formatting
  • confluence-content
  • media
  • visuals
  • navigation
  • external-content
  • communication
  • reporting
  • admin
  • development

For me Layout and Visuals could be the same idea.

In confluence the chart macro is in “Visuals and images”, see https://confluence.atlassian.com/doc/chart-macro-163415075.html

In confluence their office word viewer macro is in the “confluence content” category: https://confluence.atlassian.com/doc/office-word-macro-375849176.html

In confluence their gallery macro is in the “visuals and images” category: https://confluence.atlassian.com/doc/gallery-macro-139434.html

Conclusion:

  • I’d keep OfficeViewer in content since it’s really about displaying content.
  • Chart could be moved to Layout or a new Visuals category (or Layout could be renamed to Visuals to be more generic)
  • Gallery could be moved to Layout or a new Visuals category (or Layout could be renamed to Visuals to be more generic)

I find it useful to keep an Activity macro. I’d keep it in Notifications and remove “legacy”. See You're invited to talk on Matrix for why I think we should keep this macro and undeprecate it.

Ok so these are https://extensions.xwiki.org/xwiki/bin/view/Extension/Notifications%20Application/#HMacrosforsettings

Initially I thought I’d move them to “Developers” since they are useful if you want to build your own custom UI for setting notifications. However I think they’re not enough reusable for that. I’m not even sure why we made macros for them. Maybe @gdelhumeau could explain the idea behind them? So for now I’d move them to “Internal” indeed.

Same as above: I’d move them to “Internal”.

I don’t think these one and the previous ones are deprecated. They’re even probably used in the notifications UI on the user profile pages and in the admin UI.

Agreed.

I chose Content for async macro because it can indeed be used for any kind of content and is not limited to scripts. Now what is also probably true is that developers might be the only users who actually care about this kind of thing in practice, so I guess it’s a +1 to keep it in Content and +0 to move to Development if there is a strong push to move it from others.

Those are important macros for anyone who write a wiki macro, so Development make more sense to me and I really don’t see what would be the rationale to make it Internal.

Another possibility would be to introduce some new category dedicated to wiki macros, but then I think we would need to sub category system to have “wiki macro” be a sub category of Development. I guess what would be even nicer if that they show up in Development only when you are in the context of a wiki macro, that’s another level of complexity…

+1

I agree that in general it does not make sense to have macros with (legacy) suffix, if those really are legacy then they should go to the dedicated Deprecated category.

The rationale is that these are not macros you can include in the content of your wiki pages (they’re specific to the use case of wiki macros).

BTW what happens if you use them in wiki content? :slight_smile:

For me Internal means macro that you are not really supposed to use directly which is not the case here. Writing wiki macro is definitely not some internal feature.

They don’t do anything (unless of course if you include that content in a wiki macro).

You are not supposed to use these macros directly in wiki content. Ideally they should show up only when editing a wiki macro’s content xproperty using the WYSIWYG editor.

Wiki macros are wiki content. Again here we are talking about things which make sense in some wiki content and not some other which does not have anything to do with the concept of internal to me.

It does for me since the wikimacrocontent (for ex) should be “Internal” (not shown) when editing the content of wiki page, while it should be “Development” when editing a WikiMacroClass’s content xproperty. In other words, the category depends on the use case.

+1 to introduce a new category for them and ideally to not display that category when editing a page.
Note that right now you cannot edit the WikiMacroClass code with the WYSIWYG editor, so with the current situation it’s 100% useless to display those macros to the users. So putting it in development make sense only if we improve this.

+1 to put them internal. Note that the only parameter they have is to chose for which user to manipulate the settings. I don’t see how they can be used for a new application.

This one is really deprecated and is not used anymore in XS since 13.2RC1. I kept it only for backward compatibility reason since it’s documented. IMO it can be either be put in Deprecated or Internal, but it shouldn’t be proposed to the users.

Yes I already talked about that but we don’t have this feature right now.

Isn’t this something that should be fixed to be consistent with other wiki content ?