Shopping Basket

 x 

Cart empty


Log In

Find Us Elsewhere

SSL

Forum Search

Keyword

This is the documentation for the Spiral Paid Download Plugin for Virtuemart. This extension is implemented as a custom plugin field for Virtuemart - you can find general information about how custom plugin fields work here.

Installation

Custom plugins, like all Virtuemart plugins, are also Joomla plugins, and to use them you must first upload and install them using the Joomla installer, then enable them in the plugin manager.

In your Joomla admin, go to Extensions->Manage->Install, then browse for the file that you downloaded. Alternatively you can paste your download URL on the "Install from URL" tab.

When you get the message saying that it has been installed, go to Extensions->Plugins. Find the plugin (you can type 'download' in the search field), click the red button next to it to enable it.

Create a Custom Plugin Field

Now you need to switch to the Virtuemart and go to products->custom fields, then click the 'New' to start creating a new plugin field which you will later attach to your products.

You will see a list of parameters. You need to set the Custom Field Type parameter to 'plugin'. You should then see a select box appear at the bottom of the list labelled 'Select a plugin'. You should see the spiral download plugin listed, if not, you have forgotten to enable it.

spiraldownload

Select the spiral download plugin, then you should see the parameters for the plugin appear. You can set these as you require:-

spiraldownload2

Going back to the top of the parameters list, you should also set a title for the plugin, this is the name of the field that will be displayed in the product editor and on the product page, so make it informative, eg 'product download'. You will also need to set 'Cart Attribute' to yes. If you are using Virtuemart 3, set 'Cart Input' to no.

You should leave 'Default' alone, this value is important to the correct functioning of the plugin, and once you have saved the parameters it should be set automatically to the system name of the plugin. You can leave the other parameters alone for now, though you can add a description if you want. Click 'Save and close' when you are finished. Note that you only need to create the custom field once, you will be able to attach it to as many products as you want to have downloads for, with a different downloadable file for each product.

Synchronise Download Media - For Local Files

If your are selling files hosted on your own server then you will need to upload them to your download folder then make sure that they are included in the Virtuemart media table.

Products for download are stored in the Virtuemart 'safe' path. If you have not set this already then you can do so by going into the Virtuemart configuration, and clicking on the templates tab. The safe path is listed under 'Media Files Settings'. It should be an absolute path, not one relative to your Joomla root. It is best to use one that is outside your domain directory and which is not accessible by http:, to prevent direct downloads. For example:-

/home/sites/example.com/downloads/

If the folder does not already exist you must create it.

This folder will be used to store all files for download, also your invoices. If you don't know the path on your server then you will need to ask your web host.

Once you have set the safe path you upload your downloadable files to this folder. In your Virtuemart admin, go to Shop->Media files, to upload a file click the "New" button. This gives you the upload screen. You can browse for the file on your computer. Set "image action" to upload. Set the "role" to "for sale". Click "save" to upload the file. You do not need to supply any other form fields, the information will be filled in automatically.

If you have a lot of files you can upload them directly to the downloads folder, for example by ftp. Then you will need to synchronise them to Virtuemart, so that Virtuemart knows they are there. Go to shop->media files, and click the 'synchronise media to Virtuemart button.

Once you have done this, the files will be available to be downloaded through the download plugin.

Connect to Your Amazon S3 Account

If you are selling files hosted on Amazon S3 you will need to install the AS3 Cloud File Manager package distributed with the download plugin (you will find the download link in your order details, or you can download it here). Upload and install it as normal using the Joomla installer, then use its options to supply the access key, and the secret key. You must obtain your Amazon S3 credentials through your Amazon Web Services account (more on this here).

If you have done this correctly you should be able to see all the buckets and objects that you have on your S3 account.

Connect to your Dropbox Account

If you are selling files hosted on Dropbox you will need to install the AS3 Cloud File Manager package distributed with the download plugin (you will find the download link in your order details, or you can download it here). Then you will need to connect to your Dropbox account as described in detail here.

Attach Download Field to Your Product

The final step is to attach the product download field to some actual products. Note that you can attach this field to as many products as you want. Open up a product in the Virtuemart product editor, and click on the custom fields tab. Under the 'custom field type' heading you should see the product download field listed, select this. You should see the parameters for the custom field appear.

spiraldownload3

The first thing to do is to set the file that will be downloadable. If you have synchronized the download media you should see it listed in the select file box. You can give a title and description for the file which will be shown to the user. You can ignore the 'price' box, that is a general Virtuemart parameter, it is not used by the plugin, the actual price will be the normal product price set on the product information page.

If you have set the plugin up to work with Amazon S3 or Dropbox by installing the AS3 Manager package (described above), then you will see an option to select a download package (which you should have already created). Also, if you are using S3, there is a shortcut which allows you to select an S3 bucket and object. If you select the bucket first, then save the product, the list of objects in the bucket should be displayed in its select box - otherwise you can type in the name of the object instead.

If you want you can make a free download available by checking the free download box, however our free download custom plugin is a better choice to use for this purpose, it offers more and better features. You can also override the global parameters for the number and time period for which the download is available, and the download method. These options are described in more detail below. Now save the product - your download field is now set up.

Operation

You can have as many download fields per product as you want. To add more, just open up the product in the product editor and follow the procedure as described above. You can add a download field to as many products as you want, again follow the same procedure for each product.

 

Order Confirmation

Downloads are made available when the order status is set to confirmed or shipped. When an order confirmation email is sent out to a customer it will include a download link. The customer will also be able to view it by viewing their order in their Virtuemart account.

You can edit the customer's order in the Virtuemart administration if you need to change the number of downloads available or the time limit. To do this open up the order in the Virtuemart admin, and click the edit downloads link.

spiraldownload4

Unfortunately it is not possible to add additional downloadable files to an order. This is really a limitation of the Virtuemart order system and the way that custom plugins work. What you can do is to create an additional order for a customer. Our master user plugin works with the Virtuemart user system. You can use it to log in the front end of your site as the customer, and place the order for the additional product. Then you can confirm the order in the Virtuemart administration.

Download Restrictions

Download restrictions are applied to the field, not the file, so you can replace the file (for example if a new version is released) simply by editing the field to attach a new file.

There are three ways of restricting downloads: by number, or by time limit - or both. To turn one of these restrictions off you can set the corresponding parameter to 0 in the product field. Numbers of downloads are restricted per field, so if you add additional download fields to a product, each will allow the same number of downloads. The time limit for downloads is measured from the time the order was placed. If you choose to restrict by both time and number whichever limit is reached first will prevent the download. Note that you can allow additional downloads for a customer by editing the order.

Before allowing a download the plugin will check the product and order information to see if the user is entitled, so it is not possible to obtain additional files by manipulating the id in the download link.

Options Controlling the Download Type

Allow Streaming.

The default value for this is 'no', and this is usually fine. If you don't have problems you can ignore the following technical explanation and leave this option alone, unless you actually want to know more.

 

By default the plugin will use the PHP readfile() function to read the file and echo it to output. In spite of what you may sometimes read online, this is generally quite efficient even with big files, provided output buffering is turned off , because the large file does not need to be stored in the server memory, it is echoed directly to output. If output buffering is being used the file will however be stored temporary in memory, and this can lead to problems with large files. Before doing reading the file, the plugin attempts to close all output buffering, so usually there should not be a problem with using readfile().

 

If you are having problems however, and want to reduce the load on the server, the plugin can send the file in small chunks, to do this set the 'Allow Streaming' option to yes. The default speed to send chunks of 100kb per second, you can change this using the 'Max Download Speed' option, a larger value will result in a large chunk size. However to be clear, this is not true streaming, for that you use a streaming media server.

Download Type.

This option controls the mime-type and content disposition information that is sent to the browser, which controls how the download behaves when the user clicks the download link. If you choose the 'Simple file download (attachment)' option, when the user clicks the link, he/she will be presented with a file with the option of saving it to their computer.

If you choose the 'Play in browser (inline)' option, the plugin will send additional mime-type information, in the hope that the browser will be able to display or play the file. For example, with a JPEG file the user should see the image displayed, with a pdf it should be displayed, with an mp3 file should be automatically played if the browser supports this. The important thing to be aware of though is that it will depend on how the browser is set up to handle the type of file, also the user will still normally have the option of saving the file to their computer as well.

With some types of file, such as mp3s, usually play can start before the download has finished.

 More on Using the Plugin With Amazon S3

The options for download type (inline or attachment) and whether to allow streaming also apply to S3 files as for files on your server. If you select 'inline' for the download type, then the user's browser will attempt to play the file (if it has facilities for playing mp3s), otherwise the file will be downloaded. If streaming is set 'no',  the user is forwarded to the Amazon file using a time-limited URL. That might be the best option in most cases, because then Amazon handles all the downloading, it does not use any of your server resources. There is a slight disadvantage, because you cannot control then exactly the number of downloads, because the URL will be valid for the time it is limited (the default time is 10 minutes). So in theory the user could share the URL while it remains valid. That is why it is probably best to keep its time limit short, just long enough for the user to download the file (if your files are large you may need to increase the time limit in the AmazonS3 component options). But the plugin can still control the number of times and days for which its download button will work. For example, if you wanted the download button to be valid for 1 year, that would be fine. Each time the user clicks the button, a new time-limited Amazon URL is generated.

But if you want to use streaming, what will happen is that the plugin will read the file in chunks from the Amazon server, then output to the user's browser, so this does involve your server in some work, however it should never need to have the whole file in memory at one time, so probably the load will not be great. This method has some advantages, the user never has access to the actual file URL, so you can control precisely the number of downloads, also you can control the speed in the plugin options. In tests we found that between 100 and 1000K per second is probable the best. 100 is a bit slow for a large file to download fully, but if you are wanting the file to play in the browser, it is probably fast enough, particularly with mp3s,  because the mp3 can start playing before it is fully downloaded.

Categories

Donate to Us

If you like our extensions, consider making a donation to say thanks.

 

Support Forum