|
| Description: |
When the office macro is inserted from the Quick Actions menu, an office macro call with no parameter is added to the page right away and renders an error box, since it has no document to show. The include and display macros, which also show the content of a target, declare their target as mandatory, so the Quick Action opens the Edit Macro dialog with the target field to fill first. The office macro declares neither reference nor attachment as mandatory, since it needs one of the two. When an existing call sets the deprecated attachment parameter, the Edit Macro dialog also shows Reference and Attachment as two separate optional fields, not as one target to give. Declaring reference and attachment as one mandatory feature, like the Reference feature of include and display, fixes both.
A missing or unsupported file must also fail with an error that names the file, instead of the office server error or "Failed to view office attachment.".
h2. KOs covered
||Macro||Criterion||Problem||
|[office|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/office/]|L1 consistency|No mandatory parameter, unlike include and display, so the Quick Action inserts an empty call that renders an error box.|
|[office|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/office/]|I2 zero-config|Quick Actions, and the Edit Macro dialog submitted with the default values, insert {{{{office/}}}}, which renders an error box in the editor and in view mode: the office server error on a fresh XWiki Standard, or "You must specify the 'reference' parameter pointing to the office file to display." The user is never asked for the file first.|
|[office|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/office/]|C7 alternatives|{{reference}}: reference and the deprecated attachment are two ways to give the file to view, and the macro fails when neither is set, but they are not declared as one mandatory feature.|
|[office|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/office/]|C7 alternatives|{{attachment}}: when an existing call sets attachment, like {{{{office attachment="file.doc"/}}}}, Attachment is shown as a separate optional field next to Reference, not as an alternative way to give the file.|
|[office|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/office/]|E2 errors|A reference to a missing or unsupported file, like {{{{office reference="missing.png"/}}}}, gives the office server error on a fresh XWiki Standard, or "Failed to view office attachment." with a server, which names neither the file nor the parameter. Partly covered, see below.|
h2. Impact found on macro fluidity
These 4 5 KOs come from the [WYSIWYG usability audit of the macros|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/], under the criteria L1 consistency, I2 zero-config and , C7 alternatives and E2 errors of its [usability criteria|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Usability%20criteria/]. L1 consistency checks that a macro behaves like the other macros of the same kind for the mandatory content, the insertion process and its default parameter values. The [page of the macro|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/office/] has the full notes, and the [L1 consistency table|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Documentation%20status/#HL1consistency] tracks the progress on this criterion.
The E2 errors KO of office is only partly covered here, for the file to view. The same KO also reports other invalid values, covered by the other issues listed on the page of the macro, among them XCOMMONS-3847 for the conversion of the values and XRENDERING-823 for the wording of the error. |
|
