Content-Disposition

The Content-Disposition header field is an integral part of HTTP, providing directives to the recipient on how to process the response payload. Primarily, it’s used to signal whether the payload should be displayed inline within the browser’s context, or treated as a downloadable file. Additionally, it can also specify the preferred filename when saving the file.

Header Format

First, let’s familiarize ourselves with the structure of the Content-Disposition header field. Its syntax is as follows:

Content-Disposition: <disposition-type>; filename=<filename>

Here, <disposition-type> can be inline or attachment, and <filename> is an optional parameter specifying the filename.

Disposition Types

Inline

The inline directive indicates that the payload should be displayed directly within the user’s browser, if the media type is supported. For instance, when you navigate to an image URL and it opens within your browser, that’s the inline disposition type at work.

Here’s an illustration of the inline disposition type:

Response:

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Disposition: inline; filename="picture.jpg"
Content-Length: 2048

Attachment

The attachment directive, on the other hand, signifies that the payload should be downloaded and saved locally. If a filename is specified, the browser will default to it during the save file dialog, though users can modify it if they choose.

Here’s how an attachment disposition type might look:

Response:

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="report.pdf"
Content-Length: 3072

In this case, the PDF file “report.pdf” is prompted for download instead of being displayed within the browser.

Filename Parameter

The filename parameter is optional and can be included with either inline or attachment. It suggests a default filename when saving the file. If not specified, the browser may default to the filename in the URL, or generate one based on the URL’s path.

Keep in mind, when setting the filename parameter, it’s good practice to ensure it’s encoded correctly to handle special characters. Consider using RFC 5987 encoding for non-ASCII characters. For instance:

Response:

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename*=UTF-8''%E2%82%AC%20rates.pdf
Content-Length: 3072

Here, the filename “€ rates.pdf” has been encoded as “%E2%82%AC%20rates.pdf” to ensure proper handling of the euro symbol and space.

Summary

In essence, the Content-Disposition HTTP header provides control over the presentation of response payloads, making it an essential part of effective content delivery. Whether you’re aiming for direct browser display with inline, or triggering a file download with attachment, the flexibility offered by this header field facilitates an improved user experience. The filename parameter offers further customization, allowing you to suggest a default filename for saved files. As always, remember to encode special characters correctly to ensure universal compatibility.