Download response

A last helper in the response object is here to help you to render something from your callback route. This helper allows you to return a file which will be download through the client browser.

The first value sent to the method can be either a path to a file, either the content of the file itself. Again and like the two previous helper method, the download has a configuration object :

Key	Type	Description	Default value
headers	object	The headers bound to the response	{ 'Content-Disposition': 'attachment' }
statusCode	number	The status code of the response	200
isFilename	bool	To know if the first parameter of the download function is a filename or the content of the file	true
sourceFilename	string	The path of the file to read it	If isFilename is true, it will take the first parameter as value
downloadFilename	string	The name of the file the user download	The value of sourceFilename if not set
readFileOptions	string	What is the right encoding format to read the file you want to download. It's the second parameter sent to readFile if you need more informations	'utf8'

Unlike the previous helper which can be use without configuration, it is highly recommanded to setup your configuration here.

Why ? Because the downloadFilename takes the value of the sourceFilename automatically if no value is set. If your sourceFilename is a path, it contains slashes, so we can't assure you the behavior of the browser

Something good to know is that the default configuration is loaded first, then the sourceFilename is set (automatically the first parameter is set) and then your configuration. So you can just specify a configuration and send null as the first parameter, it can work too.

Like every other response built-in helper, you can use it in your route callback method. Here are some examples :

// The most basic usage
response.download('./my_files/foo.txt', {
  downloadFilename: 'your_foo_file.txt'
})

// If you have a content as a string variable and you want to make it download to your user
response.download('The content of the file downloaded', {
  isFilename: false,
  downloadFilename: 'file.txt'
})

// To illustrate what I said about the configuration which can be used alone
response.download(null, {
  isFilename: true, // useless because the default value is true but it's just to show with all the informations
  sourceFilename: './my/foo/file.bar',
  downloadFilename: 'file.txt',
  readFileOptions: { encoding: 'latin1' }// if your file is encoded with the format ISO-8859-1 for example
})

It's quite simple and it is a very useful shortcut for the download instead of coding it yourself. It's the last built-in helper for the response provided by Cherry, but of course if you want to respond something else, you can still use the response object and do whatever you want with it. It's a classic ServerResponse instance from Node.

So now, let's talk in the next chapter something more advanced... The plugins !