The download component lets a page immediately return a file to the visitor.
Instead of showing a web page, it sends the file's bytes as the whole response,
so it should be used at the very top of your SQL page (before the shell or any other page contents).
It is an error to use this component after another component that would display content.
How it works in simple terms:
You provide the file content using a data URL.
A data URL is just a text string that contains both the file type and the actual data.
Optionally, you provide a "filename" so the browser shows a proper Save As name.
If you do not provide a filename, many browsers will try to display the file inline (for example images or JSON), depending on the content type.
You link to the page that uses the download component from another page, using the button component for example.
What is a data URL?
It looks like this: data:[content-type][;base64],DATA
Examples:
Plain text (URL-encoded): data:text/plain,Hello%20world
Keep in mind that large files are better served from disk or object storage. Data URLs are best for small to medium files.
There is a big performance penalty for loading large files as data URLs, so it is not recommended.
Introduced in SQLPage v0.37.0.
Top-level parameters
name
required
type
description
data_url
REQUIRED
TEXT
The file content to send, written as a data URL (for example: data:text/plain,Hello%20world or data:application/octet-stream;base64,SGVsbG8h). The part before the comma declares the content type and whether the data is base64-encoded. The part after the comma is the actual data.
filename
TEXT
The suggested name of the file to save (for example: report.csv). When set, the browser will download the file as an attachment with this name. When omitted, many browsers may try to display the file inline depending on its content type.
No data
Examples
Simple plain text file
Download a small text file. The content is URL-encoded (spaces become %20).
select
'download' as component,
'data:text/plain,Hello%20SQLPage%20world!' as data_url,
'hello.txt' as filename;
select
'download' as component,
'report.pdf' as filename,
sqlpage.read_file_as_data_url('report.pdf') as data_url;
Serve an image stored as a BLOB in the database
Automatically detect the mime type
If you have a table with a column content that contains a BLOB
(depending on the database, the type may be named BYTEA, BLOB, VARBINARY, or IMAGE),
you can just return its contents directly, and SQLPage will automatically detect the mime type,
and convert it to a data URL.
select
'download' as component,
content as data_url
from document
where id = $doc_id;
Customize the mime type
In PostgreSQL, you can use the encode(bytes, format) function to encode the file content as Base64,
and manually create your own data URL.
select
'download' as component,
'data:' || doc.mime_type || ';base64,' || encode(doc.content::bytea, 'base64') as data_url
from document as doc
where doc.id = $doc_id;
In Microsoft SQL Server, you can use the BASE64_ENCODE(bytes) function to encode the file content as Base64.
In MySQL and MariaDB, you can use the TO_BASE64(str) function.