ocPortal Tutorial: Providing downloads

Written by Chris Graham, ocProducts

{!DOC_DOWNLOADS}

Table of contents

ocPortal Tutorial: Providing downloads

Categories

Adding a download category

The download tree after adding our category

In the download system, downloads are placed in categories, and categories together make up a tree (hierarchical) structure. When ocPortal is first installed there is just a single download category: the 'Root' category, which will be the 'parent' to the first new category 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 ocPortal: we love 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 category with children, the representative images of the children will be shown next to the other details (if rep-images exist for them).

We understand how important it is for users to be able to navigate fast around a website, so we have created a 'view the whole download tree' feature that they may use to jump straight to the category of their choosing. The data for this tree is downloaded in a very compressed format, making it fast to load. User's may also use the unified ocPortal searching system to find downloads that match their interests.

Adding a download

Do-next options are provided after adding a download, much like as is presented after managing other ocPortal content

When you add a download you have a choice as to whether to specify a URL or to attach a file. This is a common convention in ocPortal, and the higher form field always takes precedence over the lower once: hence if you specified both an upload and a URL, the upload would be used.
We recommend that you attach a file, as ocPortal can then manage it without risk of the URL being broken by something outside of the ocPortal 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 ocPortal give an error message). Therefore we recommend not to try attaching a file more than around 10MB in size.

The subcategory (where our download is being stored) is displayed

Our download, listed in it's category

For an uploaded file, you will see upon edit that the actual on-disk file (as indicated by the URL) is not predictable. ocPortal stores the true file-name 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' ocPortal so as to hide where it came from.

Important note

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

Viewing a download

When you add a download, ocPortal automatically adds a specially named gallery for it. You will actually see a convenient 'add image' button once a download is added, and also from the download-view page itself. The download gallery is attached to the actual download-view page, and whilst the ocPortal gallery system is used for adding and storage, the actual download galleries are display by the download system itself.

Editing/Deleting a download

Editing a download

Deletion options are presented on the edit screen, as is the standard in ocPortal

When you edit a download, you get a choice to replace the file. As with adding a download, a new upload takes precedence over a stated URL: so you do not need to clear out the URL field if you are attaching a new upload. You can of course, change the URL itself too, if you choose to not upload a new file.

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 ocPortal 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.
ocPortal 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 appropriate file permissions.

Concepts

Download: An entry in the download system, bound to a local file or a URL
Do-next manager: A standard ocPortal interface shown after managing content