Inline Display and Forced Download of Attachments
Reference
Whether an attachment opens in the browser or is saved to disk is decided by its mimetype and not by the reader, because a file served inline is served from the wiki's own address. Three properties of xwiki.properties decide it, for the download URL of an attachment and for the REST API alike. They are not the mimetype restriction on uploads, which turns a file down as it arrives; these three settle how a file that is already stored is served. Attachments introduces the other choices an administrator makes about an attachment.
| Property | Default | What it does |
|---|---|---|
| attachment.download.whitelist | The list below, although the line ships commented out | Only the mimetypes it names are displayed inline, and every other attachment is downloaded. |
| attachment.download.blacklist | Not set, and the line ships commented out on text/html,text/javascript | The mimetypes it names are downloaded, and every other attachment is displayed inline where the browser can. XWiki reads it only where the whitelist is absent. |
| attachment.download.forceDownload | Empty | The mimetypes it names are always downloaded, whoever attached the file. |
XWiki uses one of the first two lists and never both: it reads the blacklist only where the whitelist is absent from the file, so uncommenting the whitelist line puts the blacklist out of use whatever it holds. Leaving both commented out is not an empty configuration either. A new installation runs on the whitelist below, so a mimetype that is missing from it is downloaded rather than displayed. Where a blacklist is used instead, forbid at least text/html and text/javascript, the two the shipped line names. All three are read from xwiki.properties and nowhere else, so they hold for the whole installation and cannot be set for a single wiki or a single Page tree.
The whitelist a new installation runs on:
attachment.download.whitelist=audio/basic,audio/L24,audio/mp4,audio/mpeg,audio/ogg,audio/vorbis,audio/vnd.rn-realaudio,audio/vnd.wave,audio/webm,image/gif,image/jpeg,image/pjpeg,image/png,image/tiff,text/csv,text/plain,text/xml,text/rtf,video/mpeg,video/ogg,video/quicktime,video/webm,video/x-matroska,video/x-ms-wmv,video/x-flvOne attachment can be downloaded without touching the configuration at all, by adding force-download=1 to the query string of its URL. The parameter wins over the three properties and over the rights of whoever attached the file, which makes it the way to hand out a file that the wiki would otherwise open in a browser tab.
http://<yourwiki>/xwiki/bin/download/Sandbox/WebHome/example.html?force-download=1FAQ
I edited the properties and nothing changed. Why?
XWiki reads xwiki.properties when it starts. Stop the instance, edit the file, and start it again.
How do I tell which of the three decided a given attachment?
Ask for the attachment and read the Content-Disposition header of the answer. XWiki sends inline for a file it displays in the browser and attachment for one it downloads.
