Documentation of the "Downloads for Sale" Plugin for VirtueMart

John-Paul Briones also wrote a great tutorial about this plugin on webhostinghub.com!

1) Installation of the Plugin

The plugin is installed -- like any other Joomla and VirtueMart plugin -- in Joomla's extension manager. It will automatically be enabled upon installation.

 

2) Adding a Global Custom Field (only needed once)

After installation, the first thing to do is to create a custom field type in VirtueMart's administration backend.

• Go to "Products" -> "Custom Field" and add a new custom field type with the "New" button:
  
• Choose the following settings:
  • "Custom Field Type": "Plug-ins"
  • "Title": a nice title of your choice (displayed above the download links in the product view).
  • "Cart Attribute": "Yes" (otherwise the download links will not be shown in the orders and invoices; see also below and the FAQ).
  • VirtueMart 3.x: "Cart Input": "No" (otherwise the download links will not be shown!!!)
  • "Select a plug-in": "VM Downloads for Sale"
    
• Now choose some default values for the downloads assigned to products (they can be overridden for each product / download file separately):
  • "Link type for Invoices": Determines how the download links appear in the invoices and the order view.
  • "Link type on Product Page": As for invoices, but determines the appearance on the product details pages
  • "Type of download": Free for all / Free only for registered users / Download only after purchase of the product
  • "Status to enable paid download": Configure the order statuses when a paid download should be available to the purchaser
  • "Status after download": New order status after a file has been downloaded
• Confirm your settings by clicking "Save & Close". You now have a new custom field in the list.
  

Cart and Non-Cart Attributes

Basically, a cart attributes is a product attribut where different values indicate slightly different product variations, possibly even with a different price. On the other hand, non-cart attributes are simply fields to convey additional information to the user, but do not cause the product to be different. This difference is also the cause why those two types of custom fields are handled completely different: cart attributes will be shown next to the product price in the product page, while non-cart attributes will be shown at the bottom of the product page (unless their position is explicitly set to "ontop"). Similarly, cart attributes need to be shown in the order view and the invoice, while non-cart attributes will never appear in the invoice or order (since they only convey additional information, but do not further define the product). Here is a quick overview of the effect of cart vs. non-cart attribute on the display of the custom field in the product details page and the invoices:

	Cart attribute	Non-cart attribute
Product details page	-) displayed next to the price -) Displays "Price: No additional charge" unless explicitly disabled	-) Displayed at the bottom of the product page
Order view and Invoices	-) Displayed just below the product name	-) Not displayed at all

3) Uploading Media Files for Sale (needed for each downloadable file)

To upload the files you want to sell as downloads, you need to prepare them as media files "for sale" or "for download" in the VirtueMart backend. The file title of the media file will be displayed as the link, the filename will be taken from the uploaded file.

• In the VirtueMart administration area to go "Shop" -> "Media Files" and click on "New" to create a new media file, which we will upload in the following:
  
• In the "Media file [New]" page that appears, select the following settings in the "Image Information" section BEFORE uploading:
  • "Unique Filename": The title of the download (will be the visible text of the download link, not the downloaded filename)
  • "Role": Select "For sale", otherwise the plugin will not allow you to use this file as a download!
  • "Storing Location": "product" (i.e. this is a media file associated with products)
• In the "Upload File" section, select "Upload" and choose the file you want to upload as a downloadable product for sale in VirtueMart.
  
• Now click "Save" to upload the file to the server and create the media file in VirtueMart's database. The Media File page now displays an icon showing the file type of the file you just uploaded, and the "Role" and "Storing location" are reduced to the one option you chose before uploading (i.e. once you uploaded a file, you can't change the Rule and the storing location; That's why I stressed above that you really need to choose the correct values BEFORE uploading the file...):
   
• That's it. Your file will now be available to the plugin and can be added as a free or paid download to any VirtueMart product you like.

4) Adding a Downloadable File to a Product (needed for each downloadable file)

• Go to the VirtueMart product that you want to sell as a paid download. We will now add the "Downloads" custom field (that we added in step 2 above) to this product, so please go to the "Custom fields" tab of the product settings and add a "Downloads" custom field to the product (simply look at the "Custom Field Type:" section and select "Downloads" from the list):
  
• A new configuration area for the downloadable file will appear, which lets you select the media file for download (using the file title we assigned in step 3), how the download link will be displayed, and whether the download is free or a paid download.
• "Download file": This list contains all available media files (those that were uploaded as "for Sale" or "downloadable" in step 4 above). Simply select which file shall be downloadable for this product. If you forgot to upload any media files (or did not uploaded them as "for Sale", or did not publish them), then you will see a warning instead:
  
• "Link type in Invoices" (only for Cart Attributes), "Link type on Product Page": These settings let you choose how the link will appear in the invoices/orderviews and on the product details page. There are three possible values:
  • "No link displayed": There will be no download link at all in the invoice or the product page. Some sites want the download link for paid products only in the invoice, but not on the product page, while others don't want to clutter invoices with download links and instead want to have download links only on the product page.
  • "Compact link": The link is displayed as one single line, only showing small download icon and the file title. Use this style to preserve space (e.g. in the invoice, or if you have many downloads assigned to a product):
    
  • "Full link and information": Display a large download icon and several lines of text with a download link and further information about the download:
    
• "Type of download": Whether the download is free of charge for all your customers, only for registered customers (who need to be logged in), or a paid download, which is made available after payment is received.
  • "Free Download": The download links are always displayed (in the corresponding style selected above), and the download is possible without registereing on your site
  • "Download after registration": If a customer is not logged in, no download link will appear. But as soon as the customeris logged in, the download link will be displayed. A download is also only possible when logged in (even if someone has the URL of the download link, the download will only work if the user is logged in).
  • "Paid download": The download links are only displayed after purchase of the correspoding product. To download the file, the order number and password are needed (they are included in the URL of the download links). The URL of the download link (including the order number and password) is all that is needed to download the file. A registration is not necessary, since VirtueMart also allows users to purchase products as a Guest without registering as a Joomla/VirtueMart user on your site.
• After you have selected the correct settings, don't forget to press "Save".

It is of course possible to add multiple downloads (free and paid in any combination) to a product. Simply create multiple custom fields as described in this section. Each custom field can be configured separately, so you can have free downloads for all and downloads only after purchase attached to the same product. All your customers will be able to download the free downloads, while only those who purchased the product will have access to the paid downloads.

5)How the Download Links Appear to the User

If the user is not authorized to download (e.g. because he did not yet purchase the paid download, or because he is not logged in for registered downloads), no link and no other indication is displayed at all.

If the user is authorized to download, all three types of downloads (free, registered and paid) look similar. The following screenshots display the download links (both in compact and in full format) on the product page, in the order view and on the invoice PDF.

   

6) The "All Your Downloads" Page

This plugin also provides a page to display all downloads of all the user's orders, if the user is logged in, or the downloads of a given order for anonymous shoppers (order number and password needed). Simply use the URL

http://[BASE_URL_OF_VIRTUEMART]/index.php?option=com_virtuemart&view=plugin&name=downloads_for_sale

 to display the downloads page. If the user is logged in, all available downloads from all his/her orders are displayed. If the user is not logged in, he can provide the order number and order password to get access to the downloads of one particular order:

 

Unfortunately, in Joomla it is not possible to directly add a menu item with an internal link to that address. You can, however, add a menu item of type "External URL". In the "Link" input box, simply use "index.php?option=com_virtuemart&view=plugin&name=downloads_for_sale"

Various issues and configurations

Hiding the Price for Cart Attribute Custom Fields

By default, cart attribute custom fields are used to make small adjustments to products, like different sizes, and thus might imply different prices. So, by default VirtueMart always displays the additional cost implied by a cart attribute custom field, and even points it out if that additional cost is 0. To prevent this, go to the Virtuemart configuration, at "Configuration" -> "Configuration" -> Tab "Pricing". Make sure the two boxes for "Baseprice modifier" are unchecked.

Overriding the Output Design via Template Overrides

The appearance of the download links can be styled using Joomla's template overrides. For a general description about overriding the templates of VirtueMart plugins, see http://docs.virtuemart.net/tutorials/templating-layouts/101-how-to-overwrite-plugins.html

There are four different html templates for the "Downloads for Sale" plugin, located in plugins/vmcustom/downloads_for_sale/downloads_for_sale/tmpl/:

• Compact link in product details page: product_compact.php
• Full information link in product details page: product_long.php
• Compact link in order and invoices: order_compact.php
• Full information link in order and invoices: order_long.php

To customize any of them, simply copy the corresponding file from the tmpl directory to the directory templates/[YOURTEMPLATE]/html/vmcustom/downloads_for_sale/ and modify its contents. Joomla (and thus VirtueMart) will first take files found in that directory, and only use the files in the plugin's directory if no template overrides are found.

Using a template override as described here is usually preferred over directly modifying the files in plugins/vmcustom/downloads_for_sale/downloads_for_sale/tmpl/, because template overrides will survive plugin updates.

Prevent Shipping Methods / Automatically Select Free "Download" shipping

Unfortunately, VirtueMart 2 currently does not have any way to indicate that a product does not need any delivery at all (like downloads, or sold coupons, or sold seminar attendances, or sold lessons, etc.). So, VirtueMart will always insist on having a shipping method, and will always display a link to change the shipping address.

There are, however, some workarounds to make non-delivery product a little less painful to the user:

Shop for non-delivery items only: If your shop only sells non-delivery items (e.g. downloads), then you can simply set up one shipping method called "Download" and zero shipping costs.

Shop with physical goods and non-delivery items: This case is more complicated, since VirtueMart needs to somehow determine whether only downloadable products are in the order. As mentioned, VirtueMart has no direct setting, so the only way is to abuse some other product property to distinguish downloadable files from non-downloadable files.
One suggested method is to use the weight: set the weight of all downloadable products to 0, and the weight of all other products to a value larger than zero. Then any order with "weight" 0 consists of only downloadable goods (and does not need any delivery), while any order with weight>0 contains at least one other item.
You can then set up two shipping methods, one "Download" method for weight 0 and one "normal shipping" for weight >0.

Notice that the last suggestions does not work if e.g. the shipping costs for non-download items depend on the weight, and you also offer products with a weight of practically zero (like a gift coupon or some certificate).
In this case, you can abuse other properties like length, width or height, and use a 3rd party shipping plugin like the "Shipping by Rules" or "Advanced Shipping by Rules" plugin.

7) Automatic Updates

Starting with version 1.8.1, this plugin uses the Joomla 3.x updater to install new versions. For this to work, you need to enter your updater credentials (order number and password of the purchase at open-tools.net) in the plugin configuration page (Joomla Backend: Extensions => Plugins):

The updater will then access the download at open-tools.net with these credentials, which unlock download access. If you enter invalid credentials, then the plugin will work just fine, only updates are not available:

Please note that the automatic update feature for paid plugins (that need some kind of password to unlock the download) is NOT available in Joomla 2.5!

 

8) Frequently asked Questions

Version History

2016-03-06: Version 1.8.2: Fix warning when saving the custom field (SQL)
2016-01-03: Version 1.8.1: Automatic updates through the Joomla updater
2015-04-24: Version 1.8: Fix table creation (VM3), warning in downloads page, order data available in templates
2015-01-05: Version 1.7: Fix some php warnings
2014-11-24: Version 1.6: Update to Joomla 3.x and Virtuemart 3.x
2013-11-15: Version 1.5.4: Fix problems with large files, also send file size in http header
2013-08-26: Version 1.5.3: Fix some translations due to changed VM internals
2013-05-24: Version 1.5.2: Allow downloads not to change order status; Fix error handling
2013-05-13: Version 1.5.1: Fix non-standard order statuses
2013-05-08: Version 1.5: Fix warnings; Allow free/registered downloads for orders that do not yet allow paid downloads
2013-04-24: Version 1.4 (Add configuration for downloadable order status, and status after download)
2013-03-14: Version 1.3 (Improved error messages if files is not available; renamed plugin)
2013-02-26: Version 1.2 (Support for Jooma 1.5, added German translation)
2013-02-24: Version 1.1 (Fixed some permission problems for unconfirmend orders)
2013-02-06: Version 1.0 (initial public release)