Handle File Downloads using the AJAX Framework

Hello everyone,

We are happy to share a new feature of the AJAX framework shipped with October CMS 3.1, it can now handle downloading files. Sometimes it can be very useful to be able to get a file from an AJAX call, such as a CSV export or showing a generated PDF.

In HTML, on the same node as where the data-request attribute is, you may add a data-request-download attribute to enable this feature.

<button
    data-request="onDownloadDocument"
    data-request-download>
    Download Document
</a>

In the AJAX handler, output a Content-Disposition header starting with the string attachment. The following will download a file called hello-world.txt and shows the all the details of the response.

public function onDownloadDocument()
{
    $fileContents = 'Hello World: https://www.youtube.com/watch?v=u7JMhVI7taQ';

    return Response::make($fileContents, 200, [
        'Content-Type' => 'text/plain',
        'Content-Disposition' => 'attachment; filename="hello-world.txt"'
    ]);
}

A simpler way is to use the Response facade as described in the documentation. This method handles everything internally and accepts a local file path.

public function onDownloadDocument()
{
    $filePath = base_path('modules/media/tests/fixtures/media/images/small.png');
    return Response::download($filePath);
}

If the data-browser-target="_blank" attribute is set on the request trigger, the file will be opened in a new tab.

<button
    data-request="onOpenFileInBrowser"
    data-request-download
    data-browser-target="_blank">
    Open Document In New Window
</button>

If the data-request-download="..." attribute is set on the request trigger, the filename in this attribute will be given to the downloaded file.

<button
    data-request="onDownloadDocument"
    data-request-download="hello-friends.txt">
    Download Document
</a>

In the admin panel, the response can also be used from an element with data-control="popup" with dynamic response handling.

<button
    data-control="popup"
    data-handler="onDownloadOrPrompt"
    data-request-download
    class="btn btn-default oc-icon-random">
    Download or Prompt
</button>

This example will randomly show a popup or download a file.

public function onDownloadOrPrompt()
{
    if (rand() % 2 === 0) {
        return ['result' => 'Server is busy, try again in a moment...'];
    }
    else {
        $filePath = base_path('modules/media/tests/fixtures/media/images/small.png');
        return Response::download($filePath);
    }
}

You are welcome to inspect the October CMS AJAX documentation when using this feature:

We hope you enjoy this new addition and a special shout out to the team at inetis for helping us develop this solution. Learn more about how inetis can help your business using October CMS powered solutions.

4 Likes