Content Disposition Header

The BinariesServlet can add a Content-Disposition header to HTTP responses. This header instructs browsers to treat the file as a downloadable attachment and suggests a filename. For example:

Content-Disposition: attachment; filename=genome.jpeg

For more information about the Content-Disposition header, see Wikipedia: MIME#Content-Disposition.

Configure MIME Types for Content-Disposition in `web.xml`

To specify which MIME types should include the Content-Disposition header, set the contentDispositionContentTypes initialization parameter in the web.xml file where the BinariesServlet is defined.

When serving binary data, the servlet reads the jcr:mimeType property. If the property's value matches an entry in the contentDispositionContentTypes parameter, the servlet adds the Content-Disposition header to the response.

Example configuration:

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

You can also use glob patterns such as */* or application/* to match multiple MIME types. For example:

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

Configure Filename Source

By default, the BinariesServlet uses the handle name of the image, asset, or document as the filename in the Content-Disposition header. You can override this behavior by specifying one or more JCR properties as the filename source.

Example configuration:

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

If you specify multiple property names, the servlet uses the first property found on the resource. If none of the listed properties exist, or if you do not configure any properties, the handle name is used as the filename.

Info: Using the handle name as a fallback is supported in brXM 11.1.0 and later. In earlier versions, the servlet only used the configured properties. If no property was available or configured, the Content-Disposition header did not include a filename.

Appendix: Filename Encoding

The filename value in the Content-Disposition header is encoded based on the browser. For most modern browsers, the filename uses standard MIME encoding (for example, =?iso-8859-1?Q?=A1Hola,_se=F1or!?=). For Microsoft Internet Explorer and Opera, the filename is URL-encoded to ensure correct display.