CartThrob 9 documentation for ExpressionEngine commerce teams Visit CartThrob.com
Main docs
CartThrob.com

Download File Form (tag pair)

A video tutorial on this tag is available..

download_file_form creates a download form that submits to CartThrob download_file_action.

Because this is form-based, customers do not get a reusable direct URL in the page output. This is useful when you want tighter control over download access (for example purchased downloads shown in account/order history).

If you want a visible/shareable link instead, use get_download_link.

CartThrob supports both absolute server paths and full URLs as file sources. For large files, absolute server paths are generally the safer choice. Keeping files above web root can also improve protection, because files are not directly browsable by URL and must go through download handling.

Though CartThrob’s built-in download system is useful, more advanced tracking/governance requirements may need additional tooling.

Take a look at the image below, it shows the structure of the actual cartthrob.com website. You’ll note that the content (the website) is in one folder. This is the root. The CartThrob file itself, is stored above the root, in a folder called ct_release_file_bin. This can’t be accessed through a URL, only through a script.

Filesystem structure

Parameters

In addition to the parameters listed here, you may also use Global Form Parameters.

Field/entry lookup:

Using a file location:

entry_id

Entry ID of the product/entry that contains the download path field.

Use with field.

entry_id="123"

field

Field short name that stores the file path/URL.

Use with entry_id.

field="product_download_url"

file

File source path/URL.

Use an absolute server path (/var/www/...) or full URL.

file="/var/www/html/themes/user/cartthrob/images/cartthrob_logo_bg.jpg"

free_file

File source path/URL for explicit free-download handling.

When this is set, the download token is generated as free-file mode (FI).

free_file="/themes/user/cartthrob/images/cartthrob_logo_bg.jpg"

member_id

Restrict download access to a specific member ID.

Supported dynamic values include CURRENT_USER, {logged_in_member_id}, and {member_id}.

member_id="CURRENT_USER"

group_id

Legacy group restriction parameter.

Supported dynamic values include {logged_in_group_id} and {group_id}.

group_id="6"

role_id

Role-based restriction parameter (preferred over legacy group_id in current role-based EE installs).

When provided, it overrides group_id handling.

role_id="6"

debug

Appends file-debug output to the rendered tag content to help troubleshoot source path resolution and file metadata detection.

debug="yes"

Variables

This tag parses tagdata with globalVariables(true), so you can use global cart/customer variables plus form/error variables.

See Global Tag Variables.

Form Fields

language

Optional language code/name used for validation/error message localization in the download action flow.

<input type="text" name="language" value="en" />

Behavior and Constraints

  1. The form submits to download_file_action.
  2. If field + entry_id resolve to a path, that path is used as file source.
  3. If role_id is set, it overrides group_id handling in this tag setup.
  4. If file is set without member/group restrictions, the tag converts it to free-file mode (FI).
  5. If member/group/role restrictions are set, protected-file mode (FP) is used.
  6. On submit, the action validates member/role restrictions and forces file download when checks pass.
  7. If no valid file source is resolved, download action returns an error response.
  8. This flow does not provide built-in time-expiry links, IP limits, or download-count throttling.

Examples

Field + entry lookup (common purchased download pattern):

{exp:cartthrob:download_file_form field="product_download_url" entry_id="{item:entry_id}"}
    <input type="submit" value="Download" />
{/exp:cartthrob:download_file_form}

Standard file source with debug:

{exp:cartthrob:download_file_form file="{path=themes/cp_themes/default/cartthrob/images/cartthrob_logo_bg.jpg}" debug="yes"}
    <input type="submit" value="Download" />
{/exp:cartthrob:download_file_form}

Member-restricted download:

{exp:cartthrob:download_file_form file="/var/www/html/themes/user/cartthrob/images/cartthrob_logo_bg.jpg" member_id="CURRENT_USER"}
    <input type="submit" value="Download" />
{/exp:cartthrob:download_file_form}

Role-restricted download:

{exp:cartthrob:download_file_form file="/var/www/html/themes/user/cartthrob/images/cartthrob_logo_bg.jpg" role_id="6"}
    <input type="submit" value="Download" />
{/exp:cartthrob:download_file_form}