Download File Form (tag pair)
A video tutorial on this tag is available..
This tag creates a form, that when submitted, will download a file. Because it is form based, details of the file's original location can't be read by the customer, which protects your downloads. The download URL can't be shared. This makes it easy to protect your downloads, by restricting access to links to only those that have purchased an item. You can also place this form within a submitted_order_info tag pair to restrict guest downloads to the specific machine and session used when they purchased. If you'd like the customer to see a link, you may want to use the get_download_link tag.
This form based tag essentially replaces the get download link tag making it much simpler to build a protected download system than in the past. The other tags are great if you want to give the user the ability to save a direct link, or share the link.
Though CartThrob's file download system is a great option, we also recommend the LinkLocker Module for more robust download protection, management and tracking.
You can use an absolute server path, or an absolute link to a file on your website. Large files note: If you have large files, it is strongly recommended that you use absolute server paths. Using absolute server paths allows the system to immediately force downloading from your file location. If you use an absolute link like "http://mysite.com/file.zip", the system has to essentially gather the contents of the file together before starting the download. This process can take an enormous amount of RAM, processor power and time. Using absolute links is fine for files under 1 Mb, but for files much larger than this, using absolute server paths is recommended.
In addition to the large file issue, another good reason to use absolute server paths, is that you'll be able to store your files "above the root", which enhances the security of your files. If files are stored above the root of your website, they can not be accessed through any conventional means of direct linking through a browser, only a script like the one we employ will allow the file to be downloaded if stored above the root.
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.
Table of Contents
Parameters
In addition to the parameters listed here, you may also use any of the Global Form Parameters.
Field/entry lookup
Using a file location
entry_id
The entry id of the product that contains a reference to the download file path. Use this in conjunction with the "field" parameter
field
The name of the field that contains the download file path in your product entry. When used in conjunction with the entry_id parameter this is the simplest method of setting up the download.
file
Use a server path "/root/www/myfile.png" or an absolute link "http://whatever.com/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, then 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 group id, then the download will fail.
group_id="6"debug
This is an incredibly helpful parameter. It will output various information about your attempted download, including the file's mimetype, extension, and filename. Sometimes when parsing EE tag data, it's possible that what you THINK you are downloading is not actually what the system is seeing. This will also output the file's server location, and whether or not the file is assumed to be stored onsite, or offsite. If you have any problems at all with downloads, use this parameter to see what it is that your system is trying to download
debug="yes"Variables
See Global Tag Variables.
Form Fields
language
There are several validation messages you may encounter with unauthorized downloads. If you have a language you'd like these error messages to display in, you can add the 2 character ISO 639-1 language code (en), or the full language name (english). Language files control the contents of these validation messages.
<input type="text" name="language" value="en" />Examples
The simplest method, with debugging turned on. This method does not require the actual file name or location itself. All it requires is the entry id of an item with a file field, and the name of the file field.
{exp:cartthrob:download_file_form field="product_download_url" entry_id="{entry_id}" debug="yes"}
<input type="submit" value="submit" />
{/exp:cartthrob:download_file_form}Standard download with debugging turned on
{exp:cartthrob:download_file_form file="{path=themes/cp_themes/default/cartthrob/images/cartthrob_logo_bg.jpg}" debug="yes"}
<input type="submit" value="submit" />
{/exp:cartthrob:download_file_form}Download specific to a certain member group.
{exp:cartthrob:download_file_form file="{path=themes/cp_themes/default/cartthrob/images/cartthrob_logo_bg.jpg}" group_id ="6" }
<input type="submit" value="submit" />
{/exp:cartthrob:download_file_form}