Magento’s Downloadable product type is meant to sell files. Software, e-books, images, music or video – any type of content that can be packaged into files and downloaded can be sold using this product type. Since it is all about files, a large part of functionality implemented in module Mage_Downloadable is dedicated to deal with them: uploading and storing files, managing customer access and processing file downloads. Downloadable purchases need no physical shipping: once the order is cleared, its delivery is handled by links that the customer either gets by email or accesses by logging into his store account. In this post I will describe how to create and manage downloadable products, how are they displayed in the front-end, what specific procedures are necessary to process downloadable purchases, and how does delivery of downloads work. But before going there, let’s take a look at the configuration options of the Mage_Downloadable module.

Mage_Downloadable module settings in the back-end

Some aspects of the downloadable product functionality can be configured in the back-end. You can find these settings under Catalog > Downloadable Options:

• Order Item Status to Enable Downloads – this setting defines the order status that allows customers to download their purchased products. At “Pending” files can be downloaded immediately after the order is submitted. “Invoiced” makes download links available after the order is invoiced, which normally means that the payment is guaranteed. If an order is refunded, i.e. a credit memo is created, any previously available links are disabled and display status “Expired”.
• Default Maximum Number of Downloads – here you can define a website-wide value that will appear pre-entered in the back-end link creating form in field “Max. Downloads”. When creating a download link you can also set unlimited number of downloads by checking the “Unlimited” checkbox next to that field.
• Shareable – with this setting you can control the ability of download links to be shared. Customers who buy shareable links can share them with other people. Magento doesn’t authenticate users for shareable link requests, which means that anyone can download. In addition to this website-wide setting, you can define “shareable” status for each link individually.
• Default Link Title and Default Sample Title – these two default values are used to display titles/headings for links and samples in the product detail page (see Figure 4). The scope of these settings is “store view”, and for different store views their values can be different. This is handy when you implement a multi-language store.
• Open Links in New Window – this setting is self-explanatory: download links will open either in the same window or in a new one.
• Use Content-Disposition – here you can define what content-disposition is used when the browser downloads a file: inline or attachment. Simply put, the difference between the two is that if a requested file is served inline then your browser will attempt to open it in a browser window, e.g., an image file will be displayed in browser, or a PDF file will be opened in a viewer. The attachment content-disposition will force the browser to open a “Save As” dialog. A detailed description of content-disposition types can be found in RFC 6266.
• Disable Guest Checkout if Cart Contains Downloadable Items – guest customers get download links by email, but downloading files usually requires user authentication. Guests don’t have customer accounts to log into and can download shareable links only. Disabling guest checkout for carts with downloadable items prevents problems with guests buying non-shareable links and not being able to access their purchases.

Creating a Downloadable product

To manually create a downloadable product go to Catalog > Manage Products and click the “Add Product” button. In the next screen you must select an attribute set and a product type. If your downloadable product needs a custom attribute set and you have defined one, choose it in the first drop-down list, otherwise use the Default attribute set. Select Downloadable in the product type list and click “Continue”. The edit form for a downloadable product doesn’t differ much from that of a Simple one. But there is an important exception: compared to Simple products, Downloadables have an extra tab called Downlodable Information. Before opening it, fill out all other required attributes first. My values are:

• Name – “Sample Downloadable”,
• SKU – “smpldownld”,
• Status – “Enabled”,
• Tax Class – “Taxable Goods”,
• Visibility – “Catalog, Search”,
• Price – $100
• Description and Short Description – “Test description”
• Websites – “Main Website”
• Categories – any active category

Click “Save and Continue Edit” – this will create a new product and leave the edit form open. Now, let’s examine the Downloadable Information tab. It consists of two parts:

The first part is titled “Samples”. If you want your customers to be able to download a preview of your product, e.g., a limited trial version of a software, or a few chapters of an e-book – you can add these files here.

The second part is called “Links” and this is where the actual downloadable product files go. Note that you can define a sample for download links too. While sample downloads created in the “Samples” form above serve on a product level, these “link” samples allow defining finer preview options for individual links.

The downloadable files can be either uploaded to the shop server or referenced by a URL. Uploaded files are stored at /media/downloadable/files. In a default Magento installation read access to this directory is open to the outside world. You must restrict direct access to the downloadable files by placing an .htaccess file into /media/downloadable/ with the following contents:

#protect downloadable files from a direct access
deny from all

This will not prevent customers who bought a downloadable product from getting their files. The content delivery is performed by Magento application that takes care of authenticating customers and validating purchases.

If a file is referenced by an external URL it is also delivered by Magento that checks if a customer has right to access the downloadable link. Customers won’t see the original URL but you must make sure that Magento can access it.

For this exercise I’ve created five image files: two Hi-Res pictures (01.jpg and 02.jpg) will serve as downloadable products, their Low-Res versions (01_preview.jpg and 02_preview.jpg) will be link previews; and one Low-Res image (preview.jpg) – a composite of two pictures – will be the product sample. Now the forms look like this:

Before I save the product, I must click the “Upload Files” button so that the files are actually uploaded to the server. The upload functionality is implemented with a Flex uploader object, and you can upload multiple files without reloading the page. If you are curious how this is done, a description of Flex file uploading is available here, and there is a number of PHP tutorials on the topic such as this one explaining how to use Magento’s Flex Uploader. Once the files have been uploaded, I save the product that is now ready to be sold. This is how it looks in the front-end:

The link to the product preview https://comm170.solvingmagento.dev/downloadable/download/sample/sample_id/4/ points to the “download” controller of the Mage_Downloadable module. The controller uses the supplied sample_id value to retrieve the preview file and deliver it to the browser. The URLs of the link samples are generated in a similar fashion: https://comm170.solvingmagento.dev/downloadable/download/linkSample/link_id/3/. They use a different controller action, linkSample, and request parameter is called link_id. If the shop’s host has SSL enabled, these links will be secured with SSL.

Note the checkboxes next to the links. They appear because my product has the Links can be purchased separately setting enabled. This allows customers to configure downloadable product by selecting one or several available downloadable links. Enabling “Links can be purchased separately” also allows defining surcharges for each link. If such a surcharge is not null, choosing a link will increase the total price of the product by the specified amount. Surcharges are disabled if the “Links can be purchased separately” setting is inactive.

Front-end display of Downloadable products

Front-end layout updates of the Mage_Downloadable module are defined in file app/design/frontend/base/default/layout/downloadable.xml and can be grouped into the following categories:

• Displaying downloadable cart items in checkout steps. The layout updates file defines a custom item renderer for the existing checkout types: Onepage, Multishipping, and PayPal Express. The renderer’s block is Mage_Downloadable_Block_Checkout_Cart_Item_Renderer. The downloadable renderer uses a template nearly identical to the default cart item template. The only significant difference is a few lines of code that output titles of the selected download links (downloadable/checkout/success.phtml, lines 53 – 62). An example of a downloadable product item and its links in a cart can be seen in Figure 5. The checkout success page also gets an additional block Mage_Downloadable_Block_Checkout_Success that is responsible for displaying a link to the “My Downloads” page for customers who purchased a downloadable product.

  

  Figure 5. A downloadable products and its links’ titles in a shopping cart.
• Displaying downloadable items in order view, in invoices and credit memos. This task also requires a custom renderer that is able to output a list of purchased (invoiced, refunded) links. The renderer block is Mage_Downloadable_Block_Sales_Order_Item_Renderer_Downloadable and it uses three slightly different templates for orders, invoices, and credit memos that can be found under downloadable/sales/order/. Block classes Mage_Downloadable_Block_Sales_Order_Email_Items_Downloadable and Mage_Downloadable_Block_Sales_Order_Email_Items_Order_Downloadable are responsible for outputting downloadable items in order confirmation emails, invoice and credit memo emails. Their template files are located at downloadable/email/order/items/.
• Adding a list of downloadable purchases to the customer account area. This task is performed by two updates. One defines a new handle downloadable_customer_products that adds a new page to the customer account area. This page is titled “My Downloadable Products” and presents a customer with a list of his downloadable purchases. The list is compiled by block Mage_Downloadable_Block_Customer_Products_List and is accessible via the CustomerController‘s productsAction where the list block is loaded and rendered. The second layout update in this category extends the customer account navigation by adding a link to the “My Downloadable Products” page. Figure 6 displays an example of this page:
  
  Figure 6. A list of downloadable purchases in the customer account area.
• Displaying downloadable options in the product details page. Downloadable products, just as Bundles, Grouped, or Configurables, use a set of special blocks to output information related to their product type. This layout update is defined as follows:

  <PRODUCT_TYPE_downloadable translate="label" module="downloadable">
      <label>Catalog Product View (Downloadable)</label>
      <reference name="product.info">
          <block type="downloadable/catalog_product_view_type"
              name="product.info.downloadable" as="product_type_data"
              template="downloadable/catalog/product/type.phtml">
              <block type="downloadable/catalog_product_samples"
                  name="product.info.downloadable.samples" as="samples"
                  template="downloadable/catalog/product/samples.phtml"/>
              <block type="cataloginventory/stockqty_default"
                 name="product.info.downloadable.extra" as="product_type_data_extra"
                 template="cataloginventory/stockqty/default.phtml"/>
          </block>
      </reference>
      <reference name="product.info.options.wrapper">
          <block type="downloadable/catalog_product_links"
              name="product.info.downloadable.options" as="type_downloadable_options"
              before="-" template="downloadable/catalog/product/links.phtml"/>
          <action method="insert">
              <block>product.info.downloadable.options</block>
          </action>
      </reference>
  </PRODUCT_TYPE_downloadable>
  

  Listing 2. Downloadable product type layout for the product details page, /app/design/frontend/base/default/layout/downloadable.xml, line 217.

  The first reference is to the “product.info” block. It inserts a downloadable/catalog_product_view_type block and his two child blocks into it. The first child block is responsible for outputting a list of links to sample downloads. The second one outputs a stock threshold message “Only X left!” if a downloadable product has a limited stock (for example, a software product with limited number of available licenses) and the remaining stock is below the stock threshold. Stock threshold is defined on a website level in the back-end configuration at Catalog > Inventory > Stock Options > Only X left Threshold. Its default value is 0, which means no threshold. The stock threshold message is not displayed unless a non-zero threshold is set.

  The second part references to “product.info.options.wrapper” and inserts a block of type downloadable/catalog_product_links. This block outputs a list of download links available to the product. If the product’s link have the Links can be purchased separately setting enabled, the block will also output checkbox HTML input elements next to each link. In this case customers must select at least one link to add the product to cart. The validation of this input as well as price updates (if link surcharges are defined) are performed by a short JavaScript embedded into the block’s template file downloadable/catalog/product/links.phtml.

So far we’ve been exploring the visual side of the Downloadable product type: creating products using the back-end UI and displaying them with the front-end layout updates. Let’s make a short break here. In the next part of the Downloadable type overview we will see more code as we will look into the models and methods that make up the functionality of the Mage_Downloadable module.