How to upgrade jDownloads component from 1.9.2.11 to latest 3.x version?

This is a sraightforward process, but needs to be done carefully. It is not reversible unless you have an initial backup. This is NOT a migration from jD2.5.x on Joomla! 2.5

This migration is solely with Joomla! releases higher than Joomla! 3.2 as the platform. At time of writing it is Joomla! 3.3.6. 

If you are using Joomla! 2.5 and jD1.9.1.6 then see http://www.jdownloads.net/documentations/item/from-jd1-9-1-x-on-joomla-2-5-to-jd3-2-on-joomla-3-2

An integral part of moving to the latest release is the ability to update the new 3.2 series of jDownloads (jD-3.2) with all the Download information from your existing Version:1.9.2.11 Beta   series (jD-1.9.2).  This includes the categories, the files and all the supplementary information, such as the down load details, short and long descriptions, image files, layout files, and so on.  The imported jD-1.9.2 series layouts will have something like “(imported from 1.9.x)” appended to the layout name to distinguish them from the native jD-3.2 series versions.

We refer here to incorporating this information into the jDownloads jD-3.2 series as a 'data update'.  The jD-3.2 series are packed with new user suggested facilities and represents a major upgrade.  An overview of the new features is given elsewhere.

Note that the new style jD-3.2 series only operates on Joomla 3.2 or higher series.

These instructions apply solely to users running on Joomla 3.2 or higher

To carry out this 'data update' it is essential you follow the straight forward step by step procedure detailed below.  It is even suggested that it may be useful to print out these steps and 'tick them off' as you go to minimise the chance of missing a step.

The detailed steps are given below.

  1. Make sure that you are using the most recently published version of jDownloads, currently this is version 1.9.2.11 Beta.  If you are not running this version then you need to first update to 1.9.2.11 Beta .
  2. Create a backup file with the jDownloads backup creation function.  This also saves backup tables in your database and that is why version 1.9.2.11 Beta or higher is required.  Earlier versions of the jDownloads jD-1.9.2.x series may or may not make the backup in the same way. The default file name for the backup is backup_jdownloads_v1.9.2.11.txt.  Please note where this is located on your PC as it likely be needed later.
  3. The existing jD-1.9.2.x series translation files are not compatible with the jD-3.2 series release.  Some older language files will be removed automatically when the 1.9.2.x series is uninstalled; the remainder will be deleted during the jD-3.2 series installation and initialising sequence.  In the unlikely event you wish to make a copy of them for any reason you will find them in:
  • your-site /administrator/language/YOUR_LANGUAGE_PREFIX/com_jdownloads.ini
  • your-site /administrator/language/YOUR_LANGUAGE_PREFIX/com_jdownloads.sys.ini
  • your-site /language/YOUR_LANGUAGE_PREFIX/com_jdownloads.ini

Obviously if you do need to make any copies then that must be done before uninstalling the 1.9 series component.

  1. CSS files are also deleted when the existing 1.9.2.11 component is uninstalled.  The CSS file affecting the way items are displayed in the front end is the “jdownloads_fe.css” file.  The jD-3.2 version of “jdownloads_fe.css” has several additional styling items, that is the jD-1.9.2.x series CSS file is effectively only a subset the jD-3.2 series CSS file.  If you have made changes to “customise” the look of jDownloads on your site then it would probably be helpful to make a copy of the existing CSS file as it will aid in making similar changes to the corresponding jD-3.2 series CSS file.  The jD-1.9.2.x series file “jdownloads_fe.css” is located as shown below
    • your-site /components/com_jdownloads/jdownloads_fe.css

Should you do need to make a copy then that must be done before uninstalling the jD1.9.2.x series component.

  1. The Layout files in the older jD1.9 series are not compatible with those in the jD2,5 & jD3.2 series.  If you have customised your layouts then you should make a copy of them as they will be overwritten during the migration process.  One way is to export the the database <prefix>_jdownloads_templates table using phpMyAdmin or similar, another is to find them in the jDownloads backup file.  Or of course you could copy them from the Layouts part of the jDownloads Control Panel.  If you need a copy it needs to be saved before starting the migration or uninstalling the 1.9 series component.
  2. When migrating from jD1.9.2.11 to the jD3.2 series then the ids of the downloads are kept but the ids of the categories may change. The reason is to support the Joomla access permissions. This requires creating a new base (root) category which must be the new parent category for all other categories. As result new category ids are created.  This is important if you are using the Content Plugin.  This uses the Download and the Category ids to specify Downloads in articles or similar. A similar situation arrises if you have used a direct link
  3. Typical Content Plugin statements are:
    • {jd_file onlinelayout==Standard Files Layout v2.5}  The names of the layouts have changed so if you used this extensively it might be worthwhile making a copy of an existing layout and renaming appropriately.
    • {jd_file file==86}   This will not need changing as the Downloads retain their id during the migration.
    • {jd_file category==18 count==5}  Because the category id will in most cases have changed, this will probably  either point to a different categoy or not work at all. .
    Sometimes you may not readily recall the name of the category that is associated with a specific id. This relationship between the download title and the old id are in the saved backup taken at step 2 above, specifically in table '<prefix>_jdownloads_categories'.  The corresponding table for the Downloads is '<prefix>_jdownloads_files'. These are not the simplest of files to examine but it can be made slightly simpler by copying them and changing the extension to csv and then importing to Excel or Calc.  If you have a large number of files then exporting just the table '<prefix>_jdownloads_categories' using phpMyadmin in cPanel or its equivalent is an alternative, especially as an option in phpMyadmin is to export in csv format.  Of course if there are only a modest number of downloads then making image copies (screen shots) of the categories in the Backend is a practical approach.  Personally I also keep a record of the Downloads ids as well as a 'just in case' comfort factor.
  4. When you have double checked all of the above steps then first Uninstall the 1.9.2.11 or higher version jDownloads Component.  Joomla 3.x users should use the Uninstall function available in the Extension Manager ‘Manage’ tab in Extensions.
  5. Uninstall all other installed jDownloads plugins and modules, again using the Uninstall function in the Extension Manager ‘Manage’ tab.  Tip: It may be helpful if you set the filter near the top left of the Manage page to say down as this will list just those items with down in their name.  The filter is not case sensitive. Whilst the default admin template for Joomla! 3.2 is Isis, if you use the Hathor admin template it has an option select to choose either Site or Administrator. So for Hathor first choose Administrator to uninstall the component and then Site to uninstall the plugins.
  6. Do not delete the database items or the jdownloads and images/jdownloads folders and contents.
  7. Install the new jD 3.0 series jDownloads component. Get the new version zip file from here  and then update using the Extension Manager "Upload Pakage File" Install method. If you need more details on installation see First Time Installation
  8. As part of the install and initialising, the jD 3.2 series component will delete any remaining jD 1.9 series language files as those older ones are incompatible with the jD 3.2 series translations.
  9. After installing the current jD 3.2 series version please read the instructions shown in the jDownloads control panel.  Specifically a super user has to create default access permissions to the jDownloads component for the Joomla User Groups before the initialising process being carried out by jDownloads can complete.  These access permissions determine which user groups can make Downloads, carry out relevant administrative functions such as creating Categories and similar activities. It is of course possible to modify these access permissions later.  This stage is rather like a first time install so it may help to refer to First Time Installation - in Joomla! 3.2 or higher.  If you need more infomation on permissions then see Controlled Access to Categories and Downloads (Permissions & Access Levels).
  10. After setting the Joomla access permissions jDownloads will show two links: one that will incorporate the previous Download information, complete with categories, downloadable files, and so on, into the new version; and one which will allow you to skip this stage.  This option is only offered the first time so in normal circumstances it would be very wise to use the incorporate link.
  11. After completing the data update please check the update results messages shown on the jDownloads control panel.  These are also stored in the file your-site/administrator/jdownloads_update_log.txt
  12. If you are satisfied with the data update then please use the 'Delete all backup tables' in the jDownloads Tools section.
  13. If you have any links in articles or similar then these may need to be remade manually - see steps 5 and 6 above.
  14. Any additional standard jDownloads modules and plugins are automatically uploaded and installed with the new jD 3.2 series .
  15. Very occaisionally the Joomla! permissions are not set up correctly, specifically they do not 'cascade' properly and result in failures to download and/or to upload.  It seems to be related to the way categories and Downloads were created/edited/deleted in the jD1.9.x series.  If this happens then see article Permissions problems after migration to new series
  16. You may also need to visit the Menu Manager to re-enable any menu links.  This is because Joomla! may disable links associated with a component when it is uninstalled. Rightfully it does not re-enable them when the component is re-installed as it cannot know that it is the 'same' one.  This does not occur during regular update.
  17. If you are using any Language packs then also remember to load those as well.  These will also be available in the Download area. Do not use jD 1.9 series versions.**
  18. If you were using the Content plugin to show Download information in an article or similar then you may also have used something like {jd_file onlinelayout==Standard 1.4} to specify a jD1.9 series layout. This will produce an error such as "Cannot find the layout Standard 1.4".  Clearly the article or similar needs editing to refer to a jD2.5/jD3.2 series Layout. See step 6 above.

**Actually you can carry out Step 19 at any time after completing Step 7 above but we would advise doing this step after completing the data update.

Please note that with this new release translators are only just beginning their work so there may be a time gap before your language is available. Maybe you could offer to assist in doing a translation, as they say “many hands make light work”!

Version 1.6B

26 March 2015

Colin Mercer

  • Tuesday, 18 March 2014