|
| Description: |
The table of contents, the footnotes list and the dashboard macros list content that comes from the rest of the page: headings, footnotes or gadgets. Inserted on a page that has none yet, which is the usual case right after the insertion, they render nothing in view mode and only a generic placeholder, or nothing, in the editor. Nothing tells the user that the macro is there and fills in once the page has headings, footnotes or gadgets.
The macros to change, with the file where most of the fix is done:
* toc: [TocMacro.java|https://github.com/xwiki/xwiki-rendering/blob/master/xwiki-rendering-macros/xwiki-rendering-macro-toc/src/main/java/org/xwiki/rendering/internal/macro/toc/TocMacro.java].
* putFootnotes: [PutFootnotesMacro.java|https://github.com/xwiki/xwiki-rendering/blob/master/xwiki-rendering-macros/xwiki-rendering-macro-footnotes/src/main/java/org/xwiki/rendering/internal/macro/footnote/PutFootnotesMacro.java].
* dashboard: [DashboardMacro.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-dashboard/xwiki-platform-dashboard-macro/src/main/java/org/xwiki/rendering/internal/macro/dashboard/DashboardMacro.java].
The main problems:
* In the editor, an empty table of contents or footnotes list shows the generic placeholder with the macro ID, and an empty dashboard a widget 10 pixels high that disappears once the cursor leaves it.
* Nothing says what fills the macro: headings for the table of contents, footnotes for the list, gadgets added from the inline form editor for the dashboard.
The fix is an empty-state hint in the editor, like "The table of contents fills in once the page has headings", and, for the dashboard, the frame of its empty columns in view mode too. XWIKI-22046 covers the missing placeholder of macros with a blank output in general; this issue covers the hint these three macros need.
The same hint applies to a table of contents whose start level leaves out every heading of the page.
h2. KOs covered
||Macro||Criterion||Problem||
|[toc|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/toc/]|I2 zero-config|On a page without headings, {{{{toc/}}}} shows the generic "macro:toc" placeholder in the editor and renders nothing in view mode, with no hint that it fills in once headings are added.|
|[putFootnotes|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/putFootnotes/]|I2 zero-config|On a page without footnotes, {{{{putFootnotes/}}}} shows the generic "macro:putFootnotes" placeholder in the editor and renders nothing in view mode, with no hint that the list fills in once footnotes are added.|
|[dashboard|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/dashboard/]|I2 zero-config|On a page without gadgets, {{{{dashboard/}}}} shows nothing in view mode, and in the editor a widget 10 pixels high with no placeholder, which disappears once the cursor leaves it. Nothing says that gadgets are added from the inline form editor.|
|[toc|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/toc/]|E2 errors|Minor. {{{{toc start="7"/}}}}, on a page whose headings all have a lower level, renders nothing, with no message. Partly covered, see below.|
h2. Impact found on macro fluidity
These 3 4 KOs come from the [WYSIWYG usability audit of the macros|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/], under the criterion criteria I2 zero-config and E2 errors of its [usability criteria|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Usability%20criteria/]. The page of each macro, linked in the table, has the full notes and the steps to reproduce. Fixing them means giving each macro an empty state that says what fills it.
The E2 errors KO of toc is only partly covered here, for the start level. 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. |
|
