System setup

This document assumes that you are running the program eclipse for your development. This will allow you to automate most of the Joomla conversion process. For more instructions on how to setup eclipse, see Setting up your workstation for Joomla! development.

Background reading

What's new in Joomla 1.6#Developers describes most changes of Joomla 1.6 and how this affect developers. Please note that the API documentation on the joomla wiki is incomplete/inaccurate. Therefore the best way to look at the Joomla 1.6 API is to look directly at the joomla source code.

Updating your Joomla 1.5 language files to work on Joomla 1.6

Using the native php ini parser for language files has many benefits including much faster performace. Converting your exisiting Joomla 1.5 into the new format is very easy if you use a coding platform like eclipse. Search your file for *.ini in your project of choice. Then use the following search/replace values to automatically, replace exisiting quotes, add quotes to string values and update your comments.

Double quotes are NOT allowed inside the string value, except when using "_QQ_" to represent them. In case of js use, better use html entities or single quotes.

Single quotes are allowed.

Put a closing double quote at end of line if not empty or a comment. Find ^((?!#).+)\R replace with $1"\R

Put an opening double quote at start of translated string if not empty or comment. Find ^((?!#).+?\=)(.+)\R replace with $1"$2\R

Now replace the hash comments with the new semi colon. Find ^# and replace with ;

Remove any illegal strings that can prevent files loading. Find ^(null|yes|no|true|false|on|off|none)=(.+)\R and replace with nothing.

Enabling Debug System in Global configuration will display the parsing errors per file and lines.

If you do not remove the illegal strings, then your language file will load until one of them is reached. The now "illegal" strings in the language file like NO, are handled by adding a 'J' in-front of them. Just make sure you change these language strings in your XML files as well. You can include in your language file:

change in BuildRoute logic

In Joomla! 1.6, the router BuildRoute logic for each Component was changed to require a Menu Item in order to build the link.

// we need a menu item. Either the one specified in the query, or the current active one if none specifiedif(empty($query['Itemid'])){$menuItem=$menu->getActive();}else{$menuItem=$menu->getItem($query['Itemid']);}

There continue to be problems with the router. It is not uncommon to see a URL that bears the existing page URL as the "base" (if you will), followed by it's real URL. Look for these situations and report them on the tracker.

For those who have been around long enough, forcing the Menu Item on the URL was done in 1.0.12 and it turned out poorly.

Accessing component parameters in front-end

Accessing component parameters in frontend for specific menu item, we will use com_content as example : in 1.5 this was done with

In 1.6,Joomla makes the parameter object automatically available to you.

<?php$mode=$this->params->def('mode',1);?>

Changing Javascript function overrides

Joomla now has some of its Javascript functions prefixed with "Joomla". This means the functions are always unique and won't clash with other javascript functions on your server/webpage. However, you now need a different method to override the default Joomla Javascript. The Joomla 1.5 method was:

Changing removed functions

Note that the ADODB compatibility methods included function like $db->Execute($query) which now need a separate $db->setQuery($query);$db->Query();

Renamed events

A large number of the Joomla 1.5 events have been renamed. Here is the list of renamed events.

onContentAfterSave

onContentAfterTitle

onContentAfterDisplay

onContentBeforeDisplay

onContentBeforeSave

onContentSearch

onContentSearchAreas

onUserAuthenticate

onUserAfterDelete

onUserAfterSave

onUserBeforeDelete

onUserBeforeSave

onUserLogin

onUserLogout

All content events (except for search and search areas) now pass a 'context' as the first argument to alert the plugin as to what type of content is being passed. The plugin event may or may not heed this context.

This means that if you use Joomla events you have two options:
1) rename the event and your extension can only be used on Joomla 1.6
2) create your own "legacy layer" and add the new event function name to your plugin. Here is an example of the user plugin:

Changing name="adminForm" to id="adminForm"

To create your own admin forms in joomla you now need to use id="adminForm". This is because the use of the tag "name" is not valid HTML strict and has compatibility issues when used in XHTML served as XML.\. Although there is build in compatibility check to look for the old name="adminForm" tag, it is best to add the new id tag. Depending on the features you want to use you may need to include both, name="adminForm" and id="adminForm" because not all core functionality has been updated to use id's. An example of the new form code is:

Removing references to index2.php and index3.php

Joomla 1.0 had different index files to serve admin content in different manners. Joomla 1.6 has now got better way to handle this and you need to search your codebase for "index2.php" and "index3.php" to ensure you don't have any Joomla 1.0 style links. If you need to display your component without any of the other Joomla 1.6 admin content (menus, etc) then add the following to the url: "&tmpl=component"

Upgrading core table and field name usage

Many of the core Joomla tables have been simplified, combined or renamed. This was needed to get rid of some limitation dating back to Joomla 1.0. This means however that if you have code that directly manipulates Joomla tables, that you need to add a function that detects Joomla 1.6 and had different SQL queries based on the joomla version. Plase note that both tables and field names have been renamed or removed. An example is the following function that can find if a plugin is published on both Joomla 1.5 and 1.6:

function getPluginStatus($element,$folder){//get joomla specs$db=& JFactory::getDBO();$version=new JVersion;$joomla=$version->getShortVersion();if(substr($joomla,0,3)=='1.6'){//Joomla 1.6 code$query='SELECT published FROM #__extensions WHERE element='.$db->Quote($element).' AND folder='.$db->Quote($folder);}else{//Joomla 1.0/1.5 code$query='SELECT published FROM #__plugins WHERE element='.$db->Quote($element).' AND folder='.$db->Quote($folder);}$db->setQuery($query);$result=$db->loadResult();return$result;}

Changing in the XML installer manifest file

Joomla 1.6 now uses a more streamlined approach to the XML file inside the ZIP file that installs Joomla extentions.

New mootools version

Most important is that the Ajax class has been depreciated and replaced by the Request class. That means that if you use ajax calls you need to have a version switcher (below a sample code)

Also another common usuage of mootools in Joomla is the popup box. The Joomla 1.5 javascript code to close this box is:

document.getElementById('sbox-window').close();

in Joomla 1.6 you need to use:

window.parent.SqueezeBox.close();

Converting your JParameters to JForms

Joomla 1.6 now uses the JForms class to handle parameters and it has also changed the way parameters are defined in your XML files. To make menu/component/module/plugin parameters work, first you need to update the XML file. Here is an automated way to handle the bulk of the conversion. (added "" to the examples below so you can see spaces in the search query as well). Use eclipse to search and replace parameters in *.xml files

Now if you want to use your joomla extension on both Joomla 1.5 and 1.6 you will need to go to your "team synchronising" view in eclipse. Double click on your changed xml file, which will open the compare editor. Then simply copy-paste back your old Joomla 1.5 params into your new Joomla 1.6 xml file and save.

If you have custom parameter types, you will need to do some additional work. In Joomla 1.5 you would use the following code:

<params addpath="/administrator/components/com_yourname/elements">

In joomla 1.6 JParameter classes won't work and you will need to convert your jparameter fields into JForm fields. Create a new directory and copy your "old elements" into them. Then you need to load these new fields with the individual parameter

Then you still need to replace the references to $control_name and others in your new JForm field, but at least the bulk of the work has been done automatically

renamed core component names and login form parameters

A login module for Joomla 1.5 will not work without modifications on Joomla 1.6. Here is a part of the logout module that will work on both Joomla 1.5 and Joomla 1.6. You can compare the two to see the difference in input names.

These changes might also apply to front-end forms of other Joomla core components (more information needed)

ACL changes

Joomla 1.6 now has an advanced ACL system. It is unknown how this affects people that have previously used the ACL API in their extension. Please add some information here if you know more.

Plugin files now in different locations

Joomla 1.6 now creates a different hierarchy structure for plugins. Files are no longer placed where they used to be, so if your other parts of your application (comp, mods, etc.) expects them to be in a certain position, it won't work. The change has been that now plugins are in an additional subdirectory. If you only load your plugins via the 1.5 API you should be fine.

Changes to view parameters

J!1.6 has a strict new way of specifying parameters for views. J!1.5 allowed a bit of freedom where the parameters could be defined at the view.html.php level but now ithas to be at the tmpl level. AE believes the view paramters were removed.

Installation process - preflight, postflight, etc

These are new events that can screw up an existing installlation process. -1 on me for not documenting the process while stepping through xdebug. They should be totally optional access points to the installation process. But if your 1.5 install process is tricky for some reason, then these can be used to do clean up activities.

Admin template changes

Admin functions that depended on certain functions, naming conventions etc no longer work. Khepri has been removed. Other admin functions/libraries may have changed.

ACL

gid and aid have been removed. Significant changes to ACL archtecture. Bricking refers to totally locking your self and everyone else out - Last chance backdoor involves adding a emergency pw to the config file.

sys.ini language translation file

This file has 3 purposes:

1. It is used for installation process translations, when a folder language is included in the pack.

pack/language/en-gb/en-gb.extension.ini

pack/language/en-gb/en-gb.extension.sys.ini

In this case, the <description>COM_MYCOMPONENT_XML_DESCRIPTION</description> used in the sys.ini will display on installing/updating the extension.

When editing the extension in administration, it will be the .ini version of COM_MYCOMPONENT_XML_DESCRIPTION which will display.

2. It is used to replace the former .menu.ini

3. It is used to display the translated extension name in many managers.

removed include folders

Most of the 3rd party libraries (Archive, domit, js, PEAR, etc) in the include folder have been removed in J!1.6.