In this tutorial, you will learn how to customize OSDownloads to ask for a user’s first and second name and email address when they download a file.

Custom Fields is a feature that was added to the Joomla core in version 3.7. We added it to OSDownloads Pro in version 1.12.0.

By default, the OSDownloads download form will only collect an email address and a checkbox to agree to Terms & Conditions:

download form without custom fields

In this tutorial, we'll show you how to add more fields to that download form. You'll see how to add First Name and Second Name fields, as in the image below.

form to arrive to

  • In your Joomla control panel, go to Components > OSDownloads Pro > Files.
  • Create the file you wish to offer in exchange for user data. If you are a beginner to OSDownloads Pro and don't know how to create a file for downloads, please see our Getting Started with OSDownloads guide. 

IMPORTANT: Make sure you set the Require Email setting in the Requirements to Download tab to Yes. Otherwise, your download fields won't get displayed.

require email

  • In the OSDownloads Pro control panel, click Download Fields.

download fields

  • You will be taken to the OSDownloads Pro: Fields administrative page.
  • Click New.

click new

  1. Enter "First Name" as your custom field title into the Title field.
  2. Select data type from the Type field.
  3. Click Save & New.

new field

Pro tip: please keep in mind that by default a new field will be assigned to ALL your file categories. Leave it as is, if it is OK with you. Otherwise, use the Category field to assign your new custom field to specific categories only:

01 default category filtering set to all


  • Repeat these steps to create the Second Name field.
  • You should now see both of the newly created custom fields listed in your Download Fields page.

two custom fields listed

  • In the OSDownloads Pro control panel, click Options.


  • You will be taken to the OSDownloads configuration page. Click Permissions.

click permissions

  1. Make sure your permissions get displayed under the Public tab.
  2. Scroll down the page and set the Edit Custom Field Value to Allowed.
  3. Click Save & Close.

set edit custom field value to allowed

  • Now visit the file download page on your site's frontend.
  • Click the Download button.
  • You should see both custom fields now nicely displayed and ready to collect data from your visitors. 

How to Administer Data Submitted by Users

Once a user has submitted some data using the Custom Downloads Fields, you can administer their data at OSDownloads Pro > Emails. 

emails user data

The following options are available:

  • To view their data, hover over the "User Data" column:

view data

  • You can also copy the data to your computer's clipboard:

copy data to clipboard

  • You can also export the data to a CSV file:

export to csv

Starting from version 1.10.0, OSDownloads Pro features custom file fields. In this tutorial, you will learn how to use them.

Your goal in this tutorial will be to offer to your website visitors a downloadable book. Besides the book's title, image and description, you will want to display to your site visitors some additional details of the book:

  1. How many pages there are in the PDF version of the book
  2. Date when the book was released
  3. Date when it was updated
  4. What formats it is available in
  5. Its ISBN

To achieve this goal, you will create the following five custom file fields:

  1. PDF Pages
  2. Release Date
  3. Update Date
  4. Formats
  5. ISBN

Then you will create a Joomla menu item to enable your site visitors to navigate to the file webpage. Let's get started.

Step #1. Create Fields Group

  • In your Joomla back end, go to Components > OSDownloads Pro > File Field Groups:

Components > OSDownloads Pro > File field groups

  • You will see the OSDownloads Pro: Field Groups page. In the top-left corner, click the New green button:

Click new

  • You should see the OSDownloads Pro: New Field Group page. Type Book Details into the Title field and click Save & Close:

Enter book details into the title field

You just created a container for your future custom fields. Let's create the fields themselves.

Step #2. Create Custom File Fields

  • On the left sidebar, click File Fields:

Click Fle fields

  • You will see the OSDownloads Pro: Fields page. In the top-left corner, click the New green button:

Click New

  1. Type in PDF Pages into the Title box.
  2. Select the Book Details from the Field Group field.
  3. Click Save & New:

Enter title, select category and click Save

Good job! You just created your first custom file field. 

  1. Type in Release Date into the Title field for the second custom field.
  2. Select Calendar in the Type field.
  3. Select the Book Details from the Field Group field.
  4. Click Save & New.

Release date custom field

  • Repeat this step to create the Update Date calendar field.
  • Create the Format and ISBN fields the same way, you created the PDF Pages field.

You should now see all five file custom fields listed:

The five custom fields listed

Step #3. Create the File

With your file custom fields created, you are now ready to create the downloadable book file wth the file's additional details.

  • On the left sidebar, click Files:

Click Files

  • You will see the OSDownloads Pro: Files page. Click New.
  1. Type your preferred text into the Name field. For the purpose of this tutorial, I used Joomla 3 Explained.
  2. Click the gray Choose file button. Select a file from your hard drive.
  3. Enter some text into the Description text area.
  4. Click the Book Details tab:

File name and description

  • Enter a number into the PDF Pages field.
  • Click on the calendar icon next to the Release Date field:

Release Date calendar icon

  • Play with the calendar controls to select the year, month and date to your liking:

Calendar box

  • Once you are happy with the date, click on the day number:

Click on the day

  • You will see the Release Date field got populated with your selected date:

Field populated with selected date

  • Repeat this step for the Update Date field.
  • Enter some text to your liking into the Formats and ISBN fields. Your five file custom fields should now look similar to the image below:

Book details custom fields filled

  • Click Save & Close.

Step #4. Create the File Menu Item

As your file with and its custom fields are ready, it's a good time to present the file to your site visitors for download. You will achieve this by creating a menu item.

  • Go to Menus > Main menu > Add New Menu Item.

Add new menu

  • Type some text into the Menu Title box. Click on the blue Select button of the Menu Item Type field. 
  • On the Menu Item Type box, click Single File:

Single file menu item type

  • Make sure that under the OSDownloads options tab you see your downloadable file in the File field:

Make sure your file displayed in the file field

  • Click Save & Close.
  • Now check the file front end page. You should see all the additional file details that you entered into the file custom fields, nicely displayed:

Book details from the custom fields displayed









Starting from version 1.9.8, OSDownloads Pro allows you to specify to what email address(es) it will send an email notification when someone downloads a file at your site.

By default, OSDownloads Pro doesn't send any notifications. You must turn them on in OSDownloads Pro. You also need to tell OSDownloads Pro to what address(es) you would like notifications to be sent out.

  • To do this, in OSDownloads Pro control panel click the Options button:

The Options button

  • You will see the OSDownloads configuration page. Click on the Notifications tab:

The Notifications tab

This tab offers you the following five settings:

  • From Email. Optional setting. If left empty, email notifications will be sent from the email address, specified in the same field in your Joomla Global Configuration > Server > Mail Settings. Otherwise, set here a different From email address.
  • From Name. Optional. Works the same way as the above setting. If you are happy with OSDownloads Pro using the From Name you set in Joomla's Global Configuration > Server > Mail Settings, then leave this field blank. Otherwise, fill it in with a new From name.
  • Notifications. Mandatory to be set to Yes if you wish OSDownloads Pro to send email notifications. 
  • System Users. Optional. Specify here if your OSDownloads Pro notifications will be enabled for Joomla users who are set to receive Joomla system email. 
  • Additional Emails. Mandatory. Enter here email address(es) to send the download related notifications to. 

Five OSDownloads Pro email notifications settings


Both OSDownloads Free and Pro versions are your best tools for building email lists.

You can Use OSDownloads to offer a free file download in return for visitor's email address. Here's an image showing the email request:

The Before Download box

How to Set up Email Address Collection

Next, you need to create a file in OSDownload Free component. This is the file which you will offer for download in return for an email address.

  • Go to Components > OSDownolads Free > Files

Components > OSDownloads Free > Files

You will see the OSDownloads Free: Files administrative webpage. 

  • Click the New green button.

The New button

  • Enter your file name into the Name field. In our example, we called it "Free PDF SEO Guide for Beginners".

Now it is a good time to add the file itself. You have two options to do so:

1. Upload the file from your hard drive using the Choose file button:

The Choose file button

2. If you store the file somewhere in an external cloud storage service, enter the file URL into the File URL field:

The File URL field

For the purpose of this tutorial, we decided to go for the first option.

  • Enter the file description into the Description text area. 
  • Click on the Requirements to Download tab:

The Requirements for download tab

  • Since your goal is to require an email address in exchange for the file, click Yes for the Require Email setting:

Require Email > Yes

If you wish to require from your visitor to agree on certain terms and conditions:

  • Create a Joomla article with such terms and conditions
  • Click on the Select button of the Agreement Article setting and select the article
  • Click Yes for the Require Agreement setting

For the purpose of this tutorial, we will skip these steps. 

  • Click Save & Close.

Nearly done. You just created a file to offer for free download in exchange for an email address. You are ready to make it available to your site visitors.

  • Go to Menus > Main Menu > Add New Menu Item

09 create new menu item

You will see Menus: New Item administrative page. 

  1. Enter Free SEO Guide into the Menu Title field
  2. Click Select for the Menu Item Type setting.

Menu item title and Select button


  • You will see the Menu Item Type white modal box. Click OSDownloads Free > Single File:

Single File menu

  • The modal box will close and you will see the Menus: New Item page again. Click on the OSDownloads options tab:

OSDownloads Options tab

If this file is the only one you so far created in OSDownloads Free, you will see its name inside the File field:

The file name inside the File field

  • Click Save or Save & Close.
  • Now go to your site front end. You will see this menu item for the file download page nicely displayed to your visitors.

Front end menu item displayed

How It Works

When your visitor clicks on this menu item, they will see the file download page:

The file download page

Once they click the Download button, they will be required to enter their email address:

Requiring email address

After they entered their email address and clicked the Continue button, the file will become available for their download.

File available for download

It takes only a few clicks to install OSDownloads on your Joomla website.

  • In your Joomla control panel go to Extensions > Manage:

Extensions > Manage

You will see Extensions: Install administrative page.

  • Under the Upload Package File tab, click the Or browse for file green button:

Or browse for file green button

  • In the Open File box, find the Joomlashack extension you need to install and click on its file name twice
  • Everything being well, you should see successful installation messages on a light green background:

 OSDownload installed successfuly


Before installing OSDownload on your site, please make sure your site meets the following technical requirements.

In order for this extension to work normally on your site, the extension must meet some technical requirements. Once you read the instructions below, you will be able to easily identify what those requirements are. You will also learn what to do if your site fails to meet one of them.

PHP Requirements

We strongly suggest using at least PHP 5.6. PHP itself doesn't support any versions lower than 5.6. Click here to see more details on currently supported PHP versions or see the "Supported Versions" diagram below.

Currently supported PHP versions

Click here to see more details on currently supported PHP versions. Any version of PHP before 5.6 doesn’t have security updates and will not keep your site safe.

As you can see from the diagram, any release of PHP lower than 5.6 marked as "End of life". According to the PHP website, a PHP release marked as "End of life" is:

A release that is no longer supported. Users of this release should upgrade as soon as possible, as they may be exposed to unpatched security vulnerabilities.

The official Joomla recommendation is PHP 5.6 or higher. Click here to see Joomla's recommendations.

Databases Requirements

My SQL - version 5.5.3 or newer.

SQL Server - version 10.50.1600.1 or newer.

PostgreSQL - version 9.1 or newer.

Web Servers Requirements

Apache - version 2.4 and newer.

Nginx - version 1.8 and newer.

Microsoft IIS - version 7 and newer.

Joomla Version Requirements

Joomlashack supports the latest version of Joomla 3. If you're unsure about the latest version of Joomla, click here to visit At the time of writing, the latest version of Joomla is 3.8.0:

What Version of PHP, Database, and Joomla Do I Have?

If you are not sure what version of PHP or Joomla your site is currently running, here's how you can find it out:

In your Joomla site, go to System > System Information:

System Information

Both your Joomla and PHP versions will be visible on this page:

Joomla PHP supported versions

What Should I Do if My PHP Version is Below 5.6?

Copy-and-paste this text and send it to your hosting company:

I'm interested in running the Joomla web software and I was wondering if my account supported the following:

PHP 5.6 or greater
MySQL 5.5 or greater OR MariaDB 10.0 or greater
The mod_rewrite Apache module
HTTPS support

This is a Pro feature of OSDownloads. We're going to show you how to add an OSDownloads link into a Custom HTML module.

prepare content
  • You will now be able to add an OSDownloads download link into the body section of your Custom module.

OSDownloads Pro adds some cool features that you won’t find in the free version. You will find them when you click the Options button in the top right corner of OSDownloads Pro.

Constant Contact integration

Save user's emails in your mailing lists from Constant Contact.

  • Go to Components > OSDownloads Pro.
  • Click the "Options" button > Constant Contact
  • Connect to Constant Contact, set as yes
  • Add the API key and Access Token from your Constant Contact account
  • Choose a default contact list after saving the previous settings
constant contact

Note: you can assign a different Contact list inside a file (in Advanced tab) or a category (in Options tab)

Mailchimp integration, multiple lists

You can allow multiple mailing lists for MailChimp. 

  • Go to Components > OSDownloads Pro > Options > MailChimp
  • Choose the Default contact list
  • Enable or disable Opt-in (the confirmation message MailChimp send to subscribe an email account)


mailchimp lists

Note: you can assign a different Contact list inside a file (in Advanced tab) or a category (in Options tab)

Send download link to user's email

To send the download link to user's email and verify the address:

  • Edit the file through Components > OSDownloads > Files > Your file
  • In Require Email choose "yes"
  • Save and close
  • Then, go to Options (button on right-top of the screen) > Use email confirmation
  • In Use Email Confirmation set "yes"
  • In the email body, be sure to include {{download_url}}. For example:
    <a href="/{{download_url}}">Click here to download your {{name}} file</a>.
  • {{name}} and {{category}} are also available to use as tokens in the email if desired. They'll be replaced by the respective item's information in the email.
  • Save and close

This is a Pro feature of OSDownloads. We're going to show you how to add an OSDownloads link into your Joomla articles.

Use the following shortcode in your articles to display the download button:

{osdownloads download_button id-of-the-file "Custom text"}

Here are the three different parts to this shortcode:

  • osdownloads download_button ... this part never changes
  • id-of-the-file ... this is the ID number for the file.
  • "Custom text" ... this is what visitors will click on.

You can find the ID number for the file, by visiting Components > OSDownloads Pro. In this case, the ID number is 1.

id number

Here's an example of the button in action

{osdownloads download_button 1 "Download Free"}

Here's how that code appears in the article:

article code

When you publish the code, the link will appear as in the image below.

link in article

Designing the Link

It is possible to add CSS to the link. You can add CSS classes as shown in the code below. This uses Bootstrap's button class.

{osdownloads download_button.btn 1 "Download Free"}

OSDownloads Pro integrates with MailChimp Groups. This means you can send targeted emails to people who download a particular file.

Step #1. Set up groups in MailChimp

  • Login to your MailChimp account.
  • Click Lists and choose the list you want to use.
  • Click Manage Subscribers > Groups.
MailChimp groups inside a list
  • If you don't have groups already, you can create them here. I've created groups for Joomlashack extensions:
A MailChimp list with several groups

Step #2. Install OSDownloads Pro

  • You will need a copy of OSDownloads Pro.
  • Install OSDownloads Pro.
  • Go to Components > OSDownloads Pro > Options.
The Options button inside OSDownloads
  • Click the "MailChimp" tab.
  • Set "Connect to Mailchimp" to Yes.
  • Enter your Mailchimp API Key. You can find that key inside by going to Account > Extras > API keys.
mailchimp options
  • Save the Options screen.
  • You will now be able to choose from your MailChimp Lists.
  • Choose your list and your groups will appear.

On this screen, you can choose the global settings for OSDownloads' integration with MailChimp.

OSDownloads and MailChimp Groups

Step #3. Connect files to MailChimp groups

In addition to the global setting, you can also connect MailChimp to different categories and files.

  • Go to OSDownloads > Files.
  • Open a file.
  • Click the "Requirements to Download" tab.
  • Set "Require Email" to "Yes".
  • Click the "Advanced" tab.
  • You can now choose which group people will be added to when they download this file.

Step #4. Set up MailChimp marketing automation

Now you are ready to create your autoresponders. Go back to and you can use their "Automation" feature to set up your emails.

  • Go to Automation > Create Automation Workflow.
  • You can now choose "Joins List Group" to create your workflow.