Get Download Link

A video tutorial on this tag is available..

This tag creates a link, that when clicked, will download a file. This tag automatically encrypts file locations to protect your file's original location. Though this link can be shared, you can tie the download to a specific member ID, or group ID to protect access to it. This makes it easy to protect your downloads, by restricting access to only those that have purchased an item or to specific member groups. If you do not want the user to see any link at all, you can use the download_file_form instead.

Though CartThrob's file download system is a great option, we also recommend the LinkLocker Module for more robust download protection, management and tracking.

Security note: CartThrob's get_download_link encryption uses CodeIgniter's encryption classes. The following is from CodeIgniter's documentation:

Encodes the message string using bitwise XOR encoding. The key is combined with a random hash, and then it too gets converted using XOR. The whole thing is then run through mcrypt (if supported) using the randomized key. The end result is a double-encrypted message string that is randomized with each call to this function, even if the supplied message and key are the same.

Table of Contents

Parameters

Field/entry lookup

Using a file location

field

Use a custom field name to a file field; you must pair this with the entry_id parameter.

field="product_download_url"
entry_id

Use the entry_id of the entry whose file field you want to download; you must pair this with the field parameter.

entry_id="123"
file

Use a server path "/root/www/myfile.png" or an absolute link "http://whatever.com/myfile.png". Using paths relative to the webroot will not work ie: "/myfile.png".

file="/root/www/myfile.png"
member_id

{logged_in_member_id} or {member_id} also work as values. If a member ID is set here, and the person clicking the link is not logged in with that ID, the download will fail.

member_id="123"
group_id

{logged_in_group_id} or {group_id} also work as values. If a group ID is set here, and the person clicking the link is not logged in with that ID, the download will fail.

group_id="6"
language

There are several validation messages you may encounter with CartThrob's inventory system. These errors announce whether an item is out of stock. If you have a language you'd like these error messages to display in, you can add the [http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes]( character ISO 639-1 language code (en)), or the full language name (English). Language files control the contents of these validation messages.

language="en"
free_file

Use a server path "/root/www/myfile.png" or an absolute link "http://whatever.com/myfile.png". Using paths relative to the webroot will not work ie: "/myfile.png". Using this parameter will allow the file to be downloaded regardless of member group and member id.

free_file="/root/www/myfile.png"

Examples

Use an entry's custom field. This is the simplest method, as it doesn't require a file URL at all.

{exp:cartthrob:order_items member_id="CURRENT_USER"}
    <a href="{exp:cartthrob:get_download_link field="product_download_url" entry_id="{item:entry_id}" member_id="CURRENT_USER" }">Download</a>
{/exp:cartthrob:order_items}

Tie a download to a specific member ID:

<a href="{exp:cartthrob:get_download_link file="/var/www/html/themes/cp_themes/default/cartthrob/images/cartthrob_logo_bg.jpg" member_id ="{logged_in_member_id}" }"> download file</a>

Tie a download to a specific member group:

<a href="{exp:cartthrob:get_download_link file="/var/www/html/themes/cp_themes/default/cartthrob/images/cartthrob_logo_bg.jpg" group_id="3" }"> download file if you're in group 3</a>