jwplayer
Audit
- Macro ID
- jwplayer
- Source
- JW Player Macro
- Type
- Generator
- Classification reason
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-20
- Auditor
- Compared macros
- office include
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/JW%20Player%20Macro#HUsage |
| 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-contrib/macro-jwplayer/blob/master/macro-jwplayer-ui/src/main/resources/Macros/JWPlayer.xml |
| 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 | office, include |
| Other sources specific to this macro |
|---|
|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | KO | "JW Player" is the name of the JavaScript library that plays the video, not the word a user types for what the macro does, like video, movie or media player, and the macro is not a product that XWiki defines. Like mathjax, a user who does not know the library cannot guess from the name that it plays a video attached to the page. |
| D2 summary | KO | minor: "The JW Player is an open-source embeddable media player for web sites, supporting many commonly-used audio and video formats. The player is easy to configure, customize and extend." describes the library, not what the macro adds to the page: it never says that it plays an attachment of a wiki page or an external video, and "easy to configure, customize and extend" says nothing about the macro. It does not only repeat the name, since it says that it is a media player for audio and video, so it is a minor KO. |
| D3 category | OK | Content only, like the compared macros office and include. A user who looks for a video would also look in Media or Embed, but those categories do not exist, so it is recorded OK. |
| D4 quick-action | KO | Quick Actions finds the macro first for "jwplayer", "JW Player", "player" and "media". The synonym "video" ranks it 3rd, after Video and Embed content, "play" 2nd, after Video, and "movie" and "clip" do not find it. The French and German names are "JW Player", the same as the English one, a product name that is not translated, so no other language can be tested. Synonyms used: video, player, media, movie, clip, play. |
| L1 consistency | OK | compared with office and include, two generators of the Content category with no content that show a target. Like include, the macro needs its target, so Quick Actions opens the Edit Macro dialog with the mandatory attachment, where office is inserted right away since it declares no mandatory parameter. The defaults are comparable, none of the three declares one. |
| L2 doc-parameters | KO | the parameters are documented only on the legacy extensions.xwiki.org page, https://extensions.xwiki.org/xwiki/bin/view/Extension/JW%20Player%20Macro, not in the new documentation, where a search by "jwplayer", "JW Player" and "video player" finds nothing about the macro. Its parameter table has no mandatory column, so it does not say that attachment is required, and no defaults column: the defaults of autostart and repeat are in the descriptions. It describes the accepted values of attachment in two rows labelled by version, v1.0 and v2.0, instead of one description that lists the three forms. |
| L3 doc-example | KO | minor: the first example of the documentation, {{jwplayer attachment="video.mp4" /}} , is the most common use and renders the player once the attachment exists, a setup step the documentation states by its name. The block of examples fails when copied into a page, with "The [jwplayer] macro is a standalone macro and it cannot be used inline.", since its 5 lines are in one paragraph with no blank line between them: each macro on its own line renders. This is a typo of the documentation, like the one of dashboard. The audit uses {{jwplayer attachment="[email protected]" /}} . |
| I1 pattern | OK | compared with children, the reference generator, and with include. The Quick Actions entry "JW Player" opens the Edit Macro dialog, where children is inserted right away: the macro needs a file to play, like include, so it is OK. Only one Quick Actions entry inserts the macro. |
| I2 zero-config | OK | submitting the Edit Macro dialog with the default values does nothing, since the mandatory attachment is empty: the dialog stays open with no message, the generic behavior of the dialog. {{jwplayer/}} typed in the source gives "Failed to execute the [jwplayer] macro. Cause: [Parameter [attachment] is mandatory]. Click on this message for details.", acceptable for a generator that needs its target. |
| I3 instant | N/A | |
| I4 cursor | N/A | |
| I5 focus | OK | the mandatory attachment comes first, outside the Optional parameters tab, and has the focus; the four optional fields are visible without scrolling. |
| E1 wysiwyg | KO | view mode shows the player, a black frame with a play button. The editor shows only the text "Loading the video player..." right after the insertion and after saving and reopening the page, and it never changes. The macro is rendered by JavaScript, so it needs an edit-mode replacement that says which video the macro plays. |
| E2 errors | KO | most invalid values are accepted silently or give a message that does not name the parameter. autostart="maybe" and repeat="maybe" are read as false with no message. width="abc" , width="-3" and height="0" render the player at its default size with no message. attachment="" renders "Failed to execute the [velocity] macro. Cause: [The resolver parameter doesn't contain an Entity Reference of type [ATTACHMENT]]", a technical message that names another macro. A page or a file that does not exist, attachment="[email protected]" and attachment="[email protected]" , render a black player with "Error loading media: File could not be played", only once the browser has loaded it, which does not say which file is missing and does not offer to upload it; the macro reads its data from the attachment, so a missing one is not a valid use. A badly written reference, attachment="a b@@c" , gives "Error loading player: No playable sources found". The results are the same logged in as Admin and as a guest. |
| E3 nesting | KO | in a list item and in a table cell, like * {{jwplayer attachment="[email protected]" /}} , the macro is inline and renders "The [jwplayer] macro is a standalone macro and it cannot be used inline. Click on this message for details." in the editor and in view mode, with no way for the user to fix it in the editor. In a box it renders as at the top level. 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 block video frame, cannot be inside a sentence. |
| 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 | KO | OK | OK | KO | OK | OK | N/A | OK | OK | N/A | C1, minor: the name and the description speak of an attached file, "The reference to the attached media file that should be played", with examples of the page forms, where the parameter also accepts the address of an external video, like a YouTube URL, and the path of a file on the server, which the documentation lists as accepted values and the dialog does not. A user who does not read the documentation does not know that these forms exist. C4: a plain text field for a reference to an attachment, with no picker: the user has to know the syntax [email protected] and type the name of a file that is already attached. XWiki already has an attachment picker, the one of office reference, which lists the files, uploads a new one and accepts a typed reference. Since the parameter also accepts URLs and server paths, a picker needs design work, see C1. C13: N/A, the accepted values are a reference to a file, not a range or a format; the missing picker is counted under C4 and the undeclared forms under C1. |
| width | OK | OK | OK | KO | OK | OK | N/A | OK | OK | KO | C4: a plain text field for a number of pixels, where a number field could be used. For example, typing "abc" is accepted and the player keeps its size. C13: a string with no declared range, so width="abc" , width="-3" and width="0" are accepted by the dialog and render the player at its default size, with no message, see E2. The macro is a wiki macro, whose parameters cannot declare a range, see XWIKI-25197. C8: set in the macro's own usage example with the height, so it is a parameter users reach for, like the width of useravatar: recorded OK. |
| height | OK | OK | OK | KO | OK | OK | N/A | OK | OK | KO | C4: a plain text field for a number of pixels, where a number field could be used. For example, typing "abc" is accepted and the player keeps its size. C13: a string with no declared range, so height="abc" , height="-3" and height="0" are accepted by the dialog and render the player at its default size, with no message, see E2. The macro is a wiki macro, whose parameters cannot declare a range, see XWIKI-25197. C8: set in the macro's own usage example with the width: recorded OK. |
| autostart | OK | OK | OK | OK | OK | OK | N/A | OK | OK | OK | C1: the description says what it does and warns that it does not work on iOS and Android, which a user would not guess. The French and German names are "Autostart", the same as the English one, an English word that French and German users know. |
| repeat | KO | OK | OK | OK | OK | OK | N/A | OK | OK | OK | C1, minor: the description, "Whether to loop playback of the playlist or not.", speaks of a playlist, while the macro plays one file and the user cannot build a playlist with it: a user who does not know the JW Player library does not know what it means. The name "Repeat" and the true or false values are clear. |
Other notes
The jwplayer macro is a wiki macro of the community extension JW Player Macro 2.2.1, installed on the audit instance, which XWiki Standard does not bundle. The audit uses a fixture, a 3 second video.mp4 attached to MacroAudit.JwplayerFixture. The macro has no content, so the audit has no $content parameter object and E5 and E6 are N/A.
Outside the criteria: the player of the macro loads its provider scripts from the JW Player CDN, over plain HTTP, http://ssl.p.jwpcdn.com/player/v/7.9.3/provider.html5.js for an attached file and provider.youtube.js with the YouTube iframe API for a YouTube address, and it sends a ping to jwpltx.com. On a wiki served over HTTPS, a browser blocks the HTTP script as mixed content, so the player may not start there, which was not tested. The documentation lists a YouTube address as an accepted value of attachment, and it renders a player that loads the video, but that is not said by the description of the parameter, see C1 of attachment. A console error "Failed to load resource: the server responded with a status of 401" appeared once in the probe run and did not reproduce.
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 |
|---|---|---|---|
| D1 | D1 wording | JWPLAYER-28 | |
| D2 | D2 summary | JWPLAYER-28 | |
| D4 | D4 quick-action | XWIKI-25444 | |
| L2 | L2 doc-parameters | XINFRA-525 | |
| L3 | L3 doc-example | XINFRA-526 | |
| E1 | E1 wysiwyg | XWIKI-25523 (partial), JWPLAYER-30 | |
| E2 | E2 errors | XWIKI-25197 (partial) | XCOMMONS-3847 (partial), XRENDERING-823 (partial), JWPLAYER-31 (partial) |
| E3 | E3 nesting | XWIKI-23501 | |
| C1:attachment | C1 clarity, attachment | JWPLAYER-28 | |
| C4:attachment | C4 input-assistance, attachment | JWPLAYER-31 | |
| C4:width | C4 input-assistance, width | XWIKI-25197 (partial), XWIKI-25182 (partial) | JWPLAYER-29 |
| C13:width | C13 constraints, width | XWIKI-25197 | |
| C4:height | C4 input-assistance, height | XWIKI-25197 (partial), XWIKI-25182 (partial) | JWPLAYER-29 |
| C13:height | C13 constraints, height | XWIKI-25197 | |
| C1:repeat | C1 clarity, repeat | JWPLAYER-28 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XWIKI-23501 | Existing | E3 | |
| XWIKI-25197 | Existing | C13:height C13:width | C4:width C4:height E2 |
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25444 | New | D4 | |
| JWPLAYER-28 | New | C1:attachment C1:repeat D1 D2 | |
| JWPLAYER-29 | New | C4:width C4:height | |
| XWIKI-25182 | Existing | C4:width C4:height | |
| XINFRA-525 | New | L2 | |
| XINFRA-526 | New | L3 | |
| XWIKI-25523 | New | E1 | |
| JWPLAYER-30 | New | E1 | |
| JWPLAYER-31 | New | C4:attachment | E2 |
Known issues of this macro
No known issue is specific to this macro.
68 more known issues affect every macro: see the Known issues.
