Upgrading from jDownloads 3.2 to 3.9

Introduction

The jDownloads 3.9 series has introduced several enhancements, some of which are noted below.

• Revised Configuration, now uses the Joomla Options style
• Support of Joomla Custom Fields
• Improved User Groups Settings layout
OK
• More front end user group settings
• Much enhanced Control Panel
• Support multi language Associations
• Support for RTL languages such as Arabic, Hebrew, etc (from beta 7)
• Enhanced Single User Access
• Wide support for language placeholders such as   in layouts
• More features in 'Check Downloads' area
• Better Limits setting page in User Groups Settings
• Ability to add an Inquiry Form when user downloading
• Additional Layouts for jDownloads 3.9
• Checks for Overrides, active jDownloads Menu item, etc.
• Also Checks database level and PHP version when updating.
• Planned support for 'modern' style links

General

Upgrading from jDownloads 3.2 series to the 3.9 series is quite similar to a normal update.  However in order to advise about various changes the installation needs to be carried out twice.  You do need to be at least at  jDownloads 3.2.69 or later and at Joomla 3.9.x.  There are of course many extra features in the the 3.9 series which are outlined here (opens in  new page/tab).  One of the first things to note is that the Configuration section has been updated and is not in the left hand panel with Categories, Downloads, Layouts and so on.

It now uses the Joomla! Options button  which is situated at the top right of the Control Panel.  See the article Control Panel Overview for more details  (this and all other documentation or similar links in this article open in a new window/tab).

Database changes

For even better integration with Joomla! there have been some database item name changes, for example in the files data base table the name of the ID field has changed from file_id to just id, file_title has become title and so on.  Also some redundant entries have been removed.  For those wishing to upgrade an extension to be compatible with the 3.9 version please contact us through the jDownloads forum (opens in a new window/tab).

Overrides

If you have any Component , Module or Layout overrides then at the time of the upgrade they will of course be based upon jDownloads 3.2 code.This may subsequently cause the upgraded site to "misbehave".jDownloads 3.9 checks and reports if you have any jDownloads overrides each time you access the Control Panel.For Joomla! documentation on overrides see: Component & Module Overrides and Layout Overrides.

Note that the easiest way to acces an override is to go to Extensions - Templates then select Templates. This will show your Frontend templates.If you are using say Protostar then click on the 'Protostar Files and Details' link.This will then open a page with three tabs. To see if there are any overrides select the Editor tab.  This will show a list of folders, one of which is .
Click on this folder and see if there are any folders which contain the name 'jdownloads'.If there is a folder called jdownloads then you have a Component override.If you have a folder called mod_jdownloads_xxx" where the xxx is the usual name of one of the jDownload modules then you have a module override.

In summary if there is any folder in "<your_site>/templates/<your_template>/html/" with jdownloads in the name then you have an active override.You can temporarily disable these jD3.2 based overrides by changing the relevant part of the folder name from "jdownloads" to say "jdown32".

Third Party Extensions

Standard Extensions

For more details of the supported third party extensions please, see the category Extending jDownloads with other Extensions in the Documentation.  The following standard extensions are supported in jDownloads 3.9 but also see the other known compatible extensions section below.

• the AUP extensions (Alpha User Points and Alta User Points) Note Only Alta User Points has been tested in jDownloads 3.9
• the comments facility by JComments
• the comments facility by Komento
• the jDownloads Community Builder plugin

The Special Extensions for JComments, Komento and Community Builder may be found at jD3.9 extensions.  The plugin support for Alta User Points is effectively 'built in' to jDownloads but it does need installing as described in the Alta User Points article.If your present site relies heavily on other extensions to jDownloads that have not been updated by their vendors we suggest staying for the time being with the jD 3.2 series.  The upgrading is necessary because of the changes in the database item renaming.

Compatible Extensions

Please let us know via the forum if you know of any others.
The following extensions have been checked with jD3.9

1. Acymailing version 6 is available at www.acyba.com/ 
   For the jDownloads compatible plugin go to www.acyba.com/acymailing/plugins and search for jDownloads (tag plugin) v4.5.0 or higher (the word 'tag' is not related to Joomla! tags!).  This plugin supports both the 3.9 and the 3.2 series.  It is a long way down the list in the 'Files Management' section.

Custom Fields

One of the newer features in Joomla! is Joomla Custom Fields, these have far more scope with more than a dozen diferent field types compared to the four types provided in the jDownloads Custom Fields.  See for example  the article Joomla Custom Fields which describes the 15 available types.  As well as Fields, Joomla! has Field Groups which aid multilingual sites.  There are Joomla! Custom Fields that match those that are available in the jDownloads 3.2 and earlier series.As a result jDownloads 3.9 no longer supports the jDownloads custom fields, it does fully support the more extensive Joomla! Custom Fields.   jDownloads automatically transfers the old jDownloads Custom Fields into Jooma! Custom Fields during the upgrade process.As shown later extra messages indicating that the jD custom fields have been successfuly converted to Joomla! fields are displayed.Note This has only been tested with PHP7.3 and above so we advise that you ensure that you have an uptodate version of PHP.

Layouts

When upgrading all your existing layouts, with one exception as noted below, are copied over.  In addition a whole set of jDownloads 3.9 layouts are added.  These give an almost identical view as the existing default 3.2 layouts but there have been improvements in spacing and similar, particularly in the header, subheader and footer regions.  A new type of layout, Subcategories has been introduced to give a more logical arrangement. There are presently three default layouts in this section:
1. Standard Subcategories Layout  - this replaces the former 'Standard Categories Layout for paginated Subcategories 3.2' that used to be in the Categories section;
2. Standard Subcategories Layout 3.9 - this is the equivalent 3.9 version;
3. Multi-Column Subcategories Layout 3.9 - this shows subcategories in 4 column rows.It is suggested that you switch over to the 3.9 layouts as these are the layouts that will continue to be supported.

Multilingual Sites

If you have a multilingual site do not forget to install the language files for jDownloads 3.9.  See article Install jD language (opens in a new tab/window) on how to do this.  Note jDownloads comes with the jDownloads v3.9 languages for English and German already installed.

Upgrading

First Step

The first step is to check you have the latest jDownloads 3.2.69 or higher version and if necessary update to the latest version.  Using a version 3.2.68 or a lower version will cause the installation to exit without any changes to the existing jD 3.2 site.If you have an earlier series (1.9 or 2.5) then first see the jD 3.2 Migration documentation. 
The Compatibility Appendix below shows the versions of jDownloads compatible with different Joomla! versions.

Upgrading from jD 3.2.69 to jD 3.9 is, in general, similar to a regular update.  That is upgrading from the jDownloads 3.2 series to the 3.9 series is straightforward, but note because there are changes to the database and also because of the automatic conversion of any old style jDownloads custom fields then the update needs to be done twice as noted below.It is not a 'migration' requiring special treatment.  The system requirements are listed below.  Please note that jDownloads requires a higher requirement for the database than that required by Joomla!  This is due to the need to restructure some items to actually improve overall Joomla! compatibility.REMINDER: you must be at jDownloads v3.2.69 or higher in order to upgrade to the 3.9 series.

Minimum Requirements

• PHP 5.7+ (7.3+ strongly recommended, especially if the old style jDownloads Custom Fields were used.)
  
• MySQL 5.7+ or Maria DB 10.2+  (database)
  
• Joomla 3.9+ or newer
• jDownloads 3.2.69

Upgrade PHP?

This is not a requirement unles you PHP level is below the minimum level.
 However it would be a good time to upgrade your server to at least PHP 7.3+ if you have not already done so.  Also bear in mind that Joomla! 4 is expected in late 2020 and that will require PHP 7.3+ as a minimum, that is it will not support the PHP 5 series.  As a final note the PHP 7 series is faster and lighter weight than the PHP 5 series.

Any Overrides?

Please check as descibed in the Overrides section above to see if you have any jDownloads overrides.

Check for latest

So assuming you have a jDownloads v3.2 series installed please check if it is  version 3.2.69 or higher.  If it is not at least at  version 3.2.69 then the first step is to upgrade to jDownloads version 3.2.69 or higher, which is available at jDownloads 3.2 series.

Next Step

This process follows the normal upgrade process using the Install method.So go to Extensions - Manage- Install

This brings up the regular installation screen which allows a variety of uploading methods.  In this example 'Upload Package File' has been choosen.This assumes you have previously downloaded the current jDownloads 3.9 version from www.jdownloads.com to a suitable location on your device.  So drag the file to the upload panel. Installation will begin automatically.

First Install

When doing the upgrade for the first time then the upgrade will intentionally stop to show the message opposite.1. A Full Backup is advised.2. Note that some third party extensions may not work because of some database naming changes and that they need an update. See the documentation above.3. Notifies that the jDownloads Custom Fields will be converted to standard Joomla! Fields.4. Ignore the 'Error installing component' message as that is delibately generated to stop the first stage.5. To continue with the upgrade click on the 'continue update bar'.

6. After clicking on the continue update the message opposite will appear.Now continue with the second install.

However if your site has a  version of PHP or the Database handler is not at the required level then a fatal exit will have occrrued.See Minimum Requirements above.

At this stage no changes have been made to your site.  This gives you the opportunity remain for the time being with the jD 3.2 series.

Another rare problem which may occur is when you are upgrading from an early jD 3.2.69 is an Error Message such as "Extension Update: Custom install routine failure".Before taking this step it is absolutely essential to  check that your database meets the minimum requirements namely MySQL 5.7+ or Maria DB 10.2+  (database).  If you are unsure of how to check please contact us through the Forum.  Provided that you have checked the database requirements then it is necessary to execute the following in your browser, where <yourdomain.com> is replaced by your actual domain.  If the database does not meet the required level then do NOT take the following step.
https://<yourdomain.com>/administrator/index.php?option=com_jdownloads&task=tools.confirmUpdate39
This sets a software 'switch' so that the update may proceed normally.
So now start the first installation again.

Second Install

To continue the update you need to start it again just as before.That is go to Extensions - Manage - Install and proceed just the same as the first time. In the second install the above messages will not appear.

Installation Completes

The final stage shows a successful upgrade.If your site used jDownloads custom fields you will see a message indicating how many were converted and how many Downloads are involvedNote the need to click on Start jDownloads.After clicking on Start jDownloads there might be a short delay whilst the upgrade completes.  When complete the jDownloads Control Panel will be shown.

The first time you go to the jDownloads Control Panel after upgrading to the 3.9 series you will see a message such as shown opposite.

If you wish to see the stages of the Upgrade then look in the  tab on the Control Panel.

New Control Panel

The revised Control Panel is quite different from the jD 3.2 series control panel. The left hand side has links to items like Categories, Layouts and so on.  Files has been changed to Downloads but most significantly there is no link to Configuration!
Similar to Joomla! the 'configuration' setup is now accessed through the Options button   at the top right of the jDownloads Control Panel and all the other main pages in the backend.  This is consistent with the standard Joomla! style for Components. Please see the article on the Control Panel for more details.

Special Checks

jDownloads makes some special checks for items which may affect the smooth operation of jDownloads. These are generated by the Admin Stats module which is activated each time you call up the Control Panel. See also Admin Stats

No menu item

This is in effect a fatal error as jDownloads requires at least one main menu item for the frontend to work properly. 

The best one to choose is 'List all Categories'.  It may be a hidden menu.

System Module problem

This is also technically a fatal error but once detected jDownloads enables the sytem plugin for you.

Overrides Check

If you scroll down the Control Panel you may see a message such as that shown opposite the flags up the possibility that some jDownloads component and/or module overides exist.

If there are overrides as this stage it is probable that they are based on jDownloads 3.2 code. It is likely that they will now not work properly. Please see the notes above on overrides.This message will always be present whenever you have overrides to act as a reminder!.

Using F5 key

If you had a frontend view active then that will still be using jD3.2 code so clicking on say a Download button or similar may cause a 1054 error saying it could not find 'file_id' or similar.To overcome this one time happening use the keyboard F5 key as on most browsers that refreshes the page. It may happen in the backend so again use F5 key or otherwise refresh the page. On my test sites I have added a 'clear cache' app and make use of that to reload a page.

Upgrade OK but Site Problem

There are other reasons why a site may not run properly after the Upgrade is successful. 
These are rare but some that have been reported and solved are given in the article Stange Faults.
This includes notes on Site Seems Slow and Error 500 after Updating.

Upgrade Fails

In some circumstances, generally associated with a database 'fault' or inadequate run time then the upgrade may fail to work correctly.An example where the database is not sufficiently upto date is shown opposite.

No changes will have been made to the original  jD3.2 site as obviously these checks are made at an early stage.If the upgrade fails for some unknown reason later in the process then it is reversible so you can get back to your operational jD 3.2 version because the upgrade process automatically saves the jD 3.2 database tables.For details see the article Reverting Back to jD3.2.

Appendix: jDownloads and Joomla! Compatibility

These are summarised in the table below where the 'green' background indicates the supported versions.  If you are in the 'red' zone then you will need to upgrade your Joomla! to Joomla! 3.2 and then to Joomla! 3.9.  Note there is only a direct migration of jDownloads versions in the 'red' zone to the jDownloads 3.2 series.  That is you cannot go from the 'red' zone directly to the jDownloads 3.9 series.  Please see the jDownloads 3.2 documention - migration for more details.

Colin M  April 2020, updated January  2021, April 2023