Download File Form

download_file_form renders a POST form for one validated download source. The source is carried in protected form data and the customer does not receive a reusable download link. This is the preferred output for account and order-history pages when a button is sufficient.

The form does not decide whether a customer purchased the item. Render it only inside the site’s purchase/member authorization logic.

Parameters

In addition to these parameters, the tag accepts Global Form Parameters.

• entry_id
• field
• file
• free_file
• member_id
• role_id / group_id
• debug

entry_id

The current-site entry containing the named download field. Use with field.

entry_id="{item:entry_id}"

field

The field short name on that entry’s channel. ExpressionEngine File and CartThrob Download fields are approved automatically. Other fieldtypes require an exact cartthrob_download_fields entry.

field="product_download"

A missing, blank, ambiguous, or disallowed field fails closed; it does not fall back to a literal source.

Without member_id, role_id, or group_id, a resolved field download is unrestricted. The surrounding page may hide the form, but the submitted download payload has no identity restriction.

file

A direct managed-file reference, approved absolute local path, or approved HTTP(S) URL. When no member/role restriction is provided, the form treats the source as unrestricted.

file="/srv/private-downloads/manual.pdf"

free_file

Explicitly supplies a public/bearer source. With no member or role restriction, anyone able to submit the protected form payload may download it. Use free_file only when that is acceptable; use field or file with an identity restriction for purchased content.

free_file="{filedir_3}public-guide.pdf"

member_id

Restricts submission to the member. CURRENT_USER, {member_id}, and {logged_in_member_id} resolve to the current member.

member_id="CURRENT_USER"

role_id / group_id

Restricts submission to an ExpressionEngine role. role_id is the current parameter name; group_id remains its legacy alias.

role_id="6"

debug

Appends source-resolution diagnostics for the resolved file/field source to the form output. It does not diagnose free_file. Use only during development because filesystem details may be displayed.

debug="yes"

Form fields

language

Selects the language used for download validation messages.

<input type="hidden" name="language" value="en">

Recommended purchased-download example

{exp:cartthrob:order_items member_id="CURRENT_USER"}
    {exp:cartthrob:download_file_form
        field="product_download"
        entry_id="{item:entry_id}"
        member_id="CURRENT_USER"}
        <button type="submit">Download {title}</button>
    {/exp:cartthrob:download_file_form}
{/exp:cartthrob:order_items}

For a guest’s immediate order-result page, submitted_order_info can control whether the form is initially rendered, but the download cannot be bound to a member ID. Treat it as bearer access or add a site-specific order entitlement/token workflow.

Large and private files

Prefer an ExpressionEngine managed file when possible. For a raw local file, keep it outside the public web root and approve only its narrow containing directory through cartthrob_download_roots. Local delivery avoids retrieving the content over HTTP.

For external content, use a public HTTPS host and approve its exact origin through cartthrob_download_origins. CartThrob validates redirect destinations and blocks unsafe network targets.

See Downloadable products, CartThrob Download fieldtype, and Configuration Overrides.