Content Disposition Header - BloomReach Experience - Open Source CMS

This article covers a Hippo CMS version 12. There's an updated version available that covers our most recent release.

07-07-2017

Content Disposition Header

The BinariesServlet can add the Content-Disposition header field to force downloaded files to be treated as an attachment with a valid file name by the browser. For example, if properly set, the header can be like this example:

Content-Disposition: attachment; filename=genome.jpeg

For the details of "Content-Disposition" header, you can refer to http://en.wikipedia.org/wiki/MIME#Content-Disposition.

MIME type configuration for BinariesServlet in web.xml

To configure which MIME types to enable content disposition headers, set the contentDispositionContentTypes init param in the web.xml in which this servlet is defined. When the BinariesServlet tries to serve a jcr data, it reads jcr:mimeType property. So, if the mimeType property value is found in the contentDispositionContentTypes configuration, then the data will be written with Content-Disposition header. For example:

<init-param>
  <param-name>
    contentDispositionContentTypes
  </param-name>
  <param-value>
    application/pdf,
    application/rtf,
    application/excel
  </param-value>
</init-param>

In the above init param configuration, you can also set glob style configurations such as */* or application/* like the following example:

<init-param>
  <param-name>
    contentDispositionContentTypes
  </param-name>
  <param-value>
    application/*
  </param-value>
</init-param>

Filename configuration

By default, the BinariesServlet uses the handle name of the image, asset, or document the resource is embedded in. It is also possible to configure a JCR property to get the file name from, for example:

<init-param>
  <param-name>
    contentDispositionFilenameProperty
  </param-name>
  <param-value>
    demosite:filename
    demosite:attachmentname 
  </param-value>
</init-param>

If multiple property names are configured, then the first available JCR property will be chosen. If none of the properties are available for the resource, or if no properties are configured, the handle name is used.

Note: the functionality to use the handle name is available from BloomReach Experience Manager 11.1.0 onwards. Prior to that, the filename was read from the properties only; if none of the properties were available, or if no properties were configured, no filename would be added to the content disposition header.

Appendix: File name encoding issue

The file name value in Content-Disposition header is automatically encoded for each browser. For normal standard browsers, the file name is encoded by the standard MIME encoding mechanism. (e.g. "=?iso-8859-1?Q?=A1Hola,_se=F1or!?=") However, for Microsoft Internet Explorer or Opera browser, the file name is URL-encoded for proper display.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?