I agree . I looked into each one, here’s what I did concerning each.
Early validation: I added a criterion to the Usability criteria page (will do as soon as it’s not in read-only mode):
C13 constraints: When a parameter only accepts a range or a format, the macro declares it, so that the Edit Macro dialog can reject an invalid value before submitting.
It checks the declaration, for example a @Positive or @Pattern annotation on the parameter, rather than the dialog behavior, so each macro can fix it on its own. Today only the TOC and PDF TOC macros declare any. Wiki macro parameters have no way to declare constraints yet, so I created XWIKI-25197 to add one. On the dialog side I created:
XWIKI-25182: numeric parameters accept any text in the Edit Macro dialog.
XWIKI-25183: an option for the page and attachment pickers to reject references to pages that don’t exist. Allowing them stays the default, as discussed in XWIKI-13279.
Rights: hiding macros the user can’t use is XWIKI-22289. I created XWIKI-25181 for the parameter part of your point. Both need the macro descriptor to declare the required rights first. Once it does, we’ll need to check where each macro needs to use it.
Dependencies: I created XWIKI-25180, to let a parameter declare that it depends on another one. Until the descriptor supports it, every macro would fail the criterion, so in the meantime I’ll record the cases I find as a cross-macro finding linked to that issue, and it could become a criterion once XWIKI-25180 is solved.
What I wanted from the content rule is that users can tell what a content accepts without guessing macro by macro. That doesn’t depend on where the data is stored, only on whether the restriction is understandable. So I agree with your three points, with one addition on the second:
The content holds the macro’s main data, rich text or not. Data that is always short, like a heading text, can still be a parameter.
The content is edited in place, with an editing experience suited to its data. Addition: when the content accepts less than the rest of the page, the restriction is visible. Unsupported features should be disabled while the caret is inside it, and the content description (in the macro editor) says what it accepts. When the user pastes something the content doesn’t accept, an editor notification at the bottom of the screen says why, instead of the content being silently dropped or broken at rendering.
Each macro can have its own in-place experience. Controls that several macros share, like a parameter dropdown, stay consistent, as discussed in post 8.
Concretely, on the criteria page:
E3 nesting, second half: When the macro content accepts less than the rest of the page, the restriction is visible: unsupported editing features are disabled inside it and pasting unsupported content shows a notification explaining why.
E6 inplace: The content is edited in place in the editor, with an editing experience suited to its data, such as rich text or code, not in a text area of the Edit Macro dialog.
I couldn’t find the first point (The content holds the macro's main data, rich text or not.) written down anywhere for macro developers, so I’d also add a short “The Content Holds the Main Data” section to Rendering Macros (dev), right after the section on the parameters bean, and link E3 to it.
Are you okay with this? If nobody objects, I’ll update the developer documentation, and consider the content question settled.
Closing the brainstorming topic for now, feel free to still post answers, I’ll proceed to a pass with the criteria we reached after discussing until now
. I looked into each one, here’s what I did concerning each.