[title sub="Written by Chris Graham (ocProducts)"]Composr Tutorial: Providing downloads[/title]

[media width="150" description="Adding a download category" float="right"]data_custom/images/docs/tut_downloads/downloads_add_category.png[/media]
{!downloads:DOC_DOWNLOADS}

[contents]decimal,lower-alpha[/contents]

[title="2"]Setting up categories[/title]

In the download system, downloads are placed in categories, and categories together make up a tree (hierarchical) structure. When Composr is first installed there is just a single download category: the 'Home' category, which will be the 'parent' to the first new category ('child') you make. When you make a new category, you can choose a 'parent' of any existing category; by this structure, the tree is formed (by choosing a parent, you are essentially saying that your new category exists underneath it in the structure).

This tree principle applies to many areas of Composr: we strive to standardise things across our product to make things as consistent (hence, easy) as possible.

Download categories may have 'representative images'. When you are viewing a link to a category from its parent category, the representative image will be included.

Manage download categories from Content Management > Downloads.
You can delete a download category from the bottom of its edit form. The root download category cannot be deleted, however.

[title="2"]Adding downloads (and editing/deleting)[/title]

[surround]
[media width="150" description="Do-next options are provided after adding a download, as is also the case when managing other Composr content" float="right"]data_custom/images/docs/tut_downloads/downloads_do_next.png[/media]
[media width="150" description="Adding a download" float="right"]data_custom/images/docs/tut_downloads/downloads_add.png[/media]
Manage downloads from Content Management > Downloads.

[title="3"]Upload vs URL[/title]

When you add a download you have a choice as to whether to specify a URL or to attach a file. There are other options actually, explained in more detail in the [page="_SEARCH:tut_adv_downloads"]Advanced provision of downloads tutorial[/page].

We recommend that you attach a file, as Composr can then manage it without risk of the URL being broken by something outside of the Composr control.

There is a caveat with this, however, as the web was not designed for uploading large files. Essentially, the web was designed to make fast requests for web pages: attaching a large file extends the request, and widens the window for transfer errors (HTTP uploads have no 'resume' mechanism, and no good way of easily finding it a transfer is actually proceeding other than checking for network usage).

In addition, PHP may not support large files (sometimes dropping POST information as well as the file, which makes Composr give an error message).

Therefore we recommend not to try attaching a file more than around 250MB in size. Larger files should be uploaded manually, and then the URL entered.

[title="3"]Security[/title]

[title="4"]Viruses[/title]

It is your responsibility to scan files for viruses, as Composr does not include a virus scanner. This is particularly relevant to those submitted for validation by users.

[title="4"]Protection from hackers[/title]

For an uploaded file, you will see upon edit that the filename of the actual on-disk file can not be determined from the URL. Composr stores the true filename in the database, but makes it so that people cannot circumvent the download system and download files directly. When an uploaded file is downloaded, it does not actually directly indicate for the user's web browser to download the URL, but rather, it is 'piped through' Composr so as to hide where it came from. This allows you to maintain your chosen permission scheme. In addition, Composr provides an anti-leech feature which stops people placing the direct download links on other websites.

[title="3"]Images[/title]

When you add a download, Composr automatically adds a specially-named gallery for it (if the galleries addon is installed). You will actually see a convenient 'add image' icon directly after adding the download, and you will also find an equivalent link on the download-view screen itself. The download gallery is displayed in-line, within the actual download-view screen. The Composr gallery system is used for adding and storage of the images. If you have no images added for the download yet there is a shortcut on the main download add/edit form for that; otherwise you can choose which of the images should also serve as the thumbnail for the download on the download add/edit form.
[/surround]

[title="2"]Accessing downloads[/title]

[surround]
[media width="150" description="Viewing a download" float="right"]data_custom/images/docs/tut_downloads/downloads_view.png[/media]
[media width="150" description="Our download, listed in its category" float="right"]data_custom/images/docs/tut_downloads/downloads_in_subcat.png[/media]
[media width="150" description="The subcategory (where our download is being stored) is displayed" float="right"]data_custom/images/docs/tut_downloads/downloads_subcat.png[/media]
Downloads are accessed from the [tt]downloads[/tt] module ([tt]site:downloads[/tt] page-link, Content > Downloads on the default menus).

This link will take the user to the Home download category, from which they can browse through the categories until they find a download they want.

We understand how important it is for users to be able to navigate fast around a website, so we have also created a 'view the whole download tree' feature that they may use to jump straight to the category of their choosing; this is not linked in by default, but can be placed on menus by browsing for it in the menu editor's entry-point tree. The data for the tree is downloaded in a very compressed format, making it fast to load.
[/surround]

[title="2"]Editing/Deleting a download[/title]

[surround]
[media width="150" description="Deletion options are presented on the edit screen, as is the standard in Composr" float="right"]data_custom/images/docs/tut_downloads/downloads_deletion.png[/media]
[media width="150" description="Editing a download" float="right"]data_custom/images/docs/tut_downloads/downloads_edit_file.png[/media]
When you edit a download, you get a choice to replace the file.

You can delete a download from the bottom of its edit form.

When deleting a download you get the option to leave the actual file on the server. This is something you will rarely want to do, as it is best to just let Composr manage the files inside your upload directories; however it is useful in the rare case that you added a second download to use the URL of the download about to be deleted.

Composr will never try to delete a file that is not inside an upload directory, and naturally it cannot delete the file at any arbitrary URL or any file for which there aren't sufficient file permissions.
[/surround]

[title="2"]Searching inside downloads[/title]

User's may use the unified Composr searching system to find downloads that match their interests. i.e. downloads may be searched from the [tt]search[/tt] module, or the search block.

In addition, the [tt]search[/tt] module is able to search within the actual downloadable files. The following file types are supported for keyword extraction:
 - [tt].pdf[/tt]
 - [tt].txt[/tt], [tt].1st[/tt]
 - [tt].rtf[/tt]
 - [tt].xml[/tt]
 - searching text buried within binary formats (e.g. [tt].doc[/tt], [tt].ppt[/tt])
 - searching for other file types within archive files ([tt].zip[/tt], [tt].tar[/tt], [tt].gz[/tt])

[title="2"]Large files[/title]

If you're PHP build is 32 bit, files over 2GB are not supported.
If you're PHP build is 64 bit, files over 2GB are supported but the file size will not be displayed.

[concepts
 1_key="Download"          1_value="An entry in the download system, bound to a local file or a URL"
 2_key="Do-next manager"   2_value="A standard Composr screen shown after managing content"
 3_key="Download licence"  3_value="The licence a download is said to be provided under"
]Concepts[/concepts]

[title="2"]See also[/title]

 - [page="_SEARCH:tut_comcode"]Comcode and the attachment system[/page]
 - [page="_SEARCH:tut_featured"]Featuring content[/page]
 - [page="_SEARCH:tut_adv_downloads"]Advanced provision of downloads[/page]
 - [page="_SEARCH:tut_news"]News[/page]
 - [page="_SEARCH:tut_information"]Choosing how to publish[/page]

{$SET,tutorial_tags,Downloads,downloads,Content,novice}{$SET,tutorial_add_date,Aug 2008}{$SET,tutorial_summary,You can make large files available to your visitors using the Composr downloads system. Read about it.}[block]main_tutorial_rating[/block]
