office
Audit
- Macro ID
- office
- Source
- XS
- Type
- Generator
- Classification reason
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-19
- Auditor
- Compared macros
- include display
Lucas CharpentierSources
Where to gather the information the criteria are checked against, see Gather the sources.
| Source | What it gives | Used for | Where |
|---|---|---|---|
| Documentation | Parameters, default values and examples, including the most common example | L2, L3, and the criteria measured with the most common example | https://extensions.xwiki.org/xwiki/bin/view/Extension/Office%20Macro |
| Source code | How the macro declares its parameters and content: types, groups, features, advanced and hidden flags, constraints, content type, inline support | C4, C5, C7, C8, C9, C13, E4, E6 | https://github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-core/xwiki-platform-office/xwiki-platform-office-macro |
| Macro descriptor | What the Edit Macro dialog is built from, on design.xwiki.org | D1, D2, C1 to C9, E4 | Descriptor, list of macros with their categories |
| Translations | The name, description and parameter names in each language | D1, D2, D4, C1 | l10n.xwiki.org |
| Uses in XWiki pages | How XWiki itself uses the macro, a realistic example when the documentation has none | L3, C2, C3, C6, C8, C9 | Search the xwiki organization on GitHub |
| Compared macros | The audits of the macros of the same type | L1, D3 | include, display |
| Other sources specific to this macro |
|---|
|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | OK | |
| D2 summary | OK | the description says what the macro adds, but only speaks of attachments, while the reference parameter also views a remote file, like url:http://host.com/file.doc . |
| D3 category | OK | |
| D4 quick-action | KO | "office", "Office Document Viewer", the French "Liseuse de Document Office" and the synonym "document" give the macro first in the Quick Actions menu, and "viewer" gives it second, after PDF Viewer. The synonyms "word", "spreadsheet", "presentation", "powerpoint" and "excel" do not find it: "word" gives Success Box, the others give nothing. |
| L1 consistency | KO | compared with include and display, the generators that also show the content of a target. Both declare their target as a required Reference feature, so Quick Actions opens the Edit Macro dialog with the target field to fill. Office declares no mandatory parameter, see C7 of reference, so Quick Actions inserts {{office/}} right away, which renders an error box. None of the three has content, and their defaults are comparable. |
| L2 doc-parameters | KO | the parameters are documented only on the legacy extensions.xwiki.org page, https://extensions.xwiki.org/xwiki/bin/view/Extension/Office%20Macro, not in the new documentation. Its parameter table marks both reference and attachment as not optional, while the macro declares neither as mandatory and needs only one of them, and it describes filterStyles as filtering "all non-essential styles" where the macro filters the in-line CSS styles. No example shows the most common call, without filterStyles: every example sets filterStyles="false", see C8 of filterStyles. |
| L3 doc-example | OK | the first example of the documentation, {{office reference="file.doc" filterStyles="false"/}} , covers the most common use, viewing an office attachment of the current page. Every example of the page turns style filtering off, while the macro and its description recommend filtering, and the calls of the macro in XWiki itself, like {{office attachment="ppt_test.ppt"/}} , keep the default. The audit uses it without that parameter: {{office reference="file.doc"/}} . On a fresh XWiki Standard it renders the office server error, a prerequisite the documentation states under Prerequisites. |
| I1 pattern | OK | like children, the reference generator, Quick Actions inserts the macro without a dialog, and the Insert Macro dialog opens an Edit Macro dialog whose fields are all optional. Unlike children, the result is an error box, see I2. |
| I2 zero-config | KO | Quick Actions inserts {{office/}} with no dialog, and the Edit Macro dialog submitted with the default values inserts the same: both render an error box in the editor and in view mode. On a fresh XWiki Standard it is the office server error, which only an administrator can fix; with a server, the source code gives "You must specify the 'reference' parameter pointing to the office file to display." The user is never asked for the file before seeing an error. |
| I3 instant | N/A | |
| I4 cursor | N/A | |
| I5 focus | OK | no parameter is mandatory, so the measure is met, but the focus is on the Filter Styles checkbox, and the Reference picker, the file the macro needs, comes second, see C8 of filterStyles. |
| E1 wysiwyg | KO | on a fresh XWiki Standard the example shows the same office server error box in the editor and in view mode, and the rendering of a real document could not be compared without an office server. The converted document is too heavy to render in the editor anyway: the macro should show an edit-mode replacement that says which file it views. |
| E2 errors | KO | invalid values are accepted silently. {{office reference="file.doc" filterStyles="maybe"/}} reaches the execution of the macro, so "maybe" is read as false, with no message. On a fresh XWiki Standard, every invalid value, like {{office reference="missing.png"/}} , gives the office server error, which says nothing about the value; with a server, the source code wraps any failure to view the file in "Failed to view office attachment.", which names no parameter. |
| E3 nesting | KO | in a list item and in a table cell, like * {{office reference="file.doc"/}} , the macro is inline and renders "The [office] macro is a standalone macro and it cannot be used inline." in the editor and in view mode. In a box it renders as at the top level, with the office server error. The macro has no content, so the second half of the measure does not apply. |
| E4 inline-support | OK | the macro declares no inline support, and its output, a converted document with paragraphs, tables or slide images, cannot be inline. |
| E5 empty | N/A | |
| E6 inplace | N/A |
Parameters
| Parameter | C1 clarity | C2 mandatory | C3 defaults | C4 input-assistance | C5 groups | C6 order | C7 alternatives | C8 advanced | C9 technical | C13 constraints | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| attachment | N/A | OK | N/A | N/A | N/A | N/A | KO | N/A | OK | N/A | C7: see reference: shown as a separate optional field, not as an alternative of the file to view. C9: deprecated, hidden from the Edit Macro dialog unless the macro already sets it, then labelled "(Deprecated)". |
| filterStyles | OK | OK | OK | OK | OK | OK | N/A | KO | OK | N/A | C1: CSS and HTML are technical terms, but OK for a styling option, and the description states the effect: "Office content is usually better integrated in the host wiki page when styles are filtered." C8: not advanced, while it does not change what the macro does, only how the result is styled, and the calls of XWiki itself keep the default. Every example of the documentation sets it, to false, which the documentation should do less often, see L2. |
| reference | OK | OK | OK | OK | OK | OK | KO | OK | OK | N/A | C1: "Reference" is a technical name, but the description explains it, with examples of the accepted values. The English description has a typo, "Use an resource string reference", and the French one is not translated. C3: no default, and none makes sense: the field opens on its placeholder "Select or upload an office file", like the Page picker of include. C4: a picker that lists the office files, lets the user upload one, finds an office attachment of another page by its name, like "report" for report.odt on another page, and accepts a typed reference. C6: the Filter Styles checkbox comes first and gets the focus, and the file to view comes second. Not counted here: marking filterStyles as advanced, see its C8, puts the file first. C7: reference and the deprecated attachment are alternative ways to give the file, and the macro fails when neither is set, but they are not declared as a required feature. The dialog marks nothing as required, and when an existing call sets attachment, like {{office attachment="file.doc"/}} , Reference and Attachment appear as two separate optional fields. Include and display group their target in a required Reference feature. |
Other notes
The office macro needs an office server, which a fresh XWiki Standard does not start: every call, valid or not, renders "Failed to execute the [office] macro. Cause: [The wiki needs to be connected to an office server in order to view office files. Ask your administrator to configure such a server.]" in the editor and in view mode. The audit records what such a user sees. With no office server, the actual rendering of a document could not be checked for E1, E2 and E4, and the messages E2 would give once a server is connected are taken from the source code.
KOs and tickets
Every KO needs a ticket covering it, see Report the KOs. One ticket can cover several KOs. Known issues filed for this macro are suggested in italics: link them as existing tickets when they cover the KO.
| KO | Criterion | Existing tickets | New tickets |
|---|---|---|---|
| D4 | D4 quick-action | XWIKI-25444 | |
| L1 | L1 consistency | XWIKI-25507 | |
| L2 | L2 doc-parameters | XINFRA-525 | |
| I2 | I2 zero-config | XWIKI-25507 | |
| E1 | E1 wysiwyg | XWIKI-25537 | |
| E2 | E2 errors | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25507 (partial) | |
| E3 | E3 nesting | XWIKI-23501 | |
| C7:attachment | C7 alternatives, attachment | XWIKI-25507 | |
| C8:filterStyles | C8 advanced, filterStyles | XWIKI-25491 | |
| C7:reference | C7 alternatives, reference | XWIKI-25507 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XWIKI-23501 | Existing | E3 | |
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25444 | New | D4 | |
| XWIKI-25491 | New | C8:filterStyles | |
| XWIKI-25507 | New | L1 I2 C7:reference C7:attachment | E2 |
| XINFRA-525 | New | L2 | |
| XWIKI-25537 | New | E1 |
Known issues of this macro
| Issue | Title | Status | Criteria |
|---|---|---|---|
| XWIKI-23503 | 'Submit' button is active although no document is uploaded in the Office Document Viewer Macro | Closed | C2 |
68 more known issues affect every macro: see the Known issues.
