How to J4-ify your old Joomla 3 template

Details: Category: Documents; Also available:

Joomla is a beautifully matured CMS, and long term Joomlers might knowingly nod, when I say it was a bumpy ride at times. Have a look at this article 'Celebrating Joomla 4' to get an idea of the new features of Joomla 4.

If you are (relatively) new to Joomla, chances are your website uses a template compatible with Joomla 4 (or at least your template developer provides a fully J4 compatible version of the template). Then you are lucky and this article is of no concern for you. But what if your website has been running for years now, and you are considering a migration from Joomla 3 to Joomla 4?

Before you decide, you have to answer a number of questions and the new Pre-Update-Checker in Joomla 3.10 (https://magazine.joomla.org/all-issues/august/pre-update-check-your-path-to-joomla-4 ) helps you a lot with these questions. In this article, I am focussing on one specific of these questions: How to handle your current Joomla 3 frontend template?

Your choices

As always in life, you have multiple paths to choose from:

You can use the opportunity to abandon your old template and fully embrace the future. I am sure by the time you read this, there will be plenty of templates available for Joomla 4.
You want to use your current template on your new Joomla 4 website as well. In this case, again, you have two possible choices:
1. Your template developer provides an updated version of your template, compatible with Joomla 4.
2. There is no updated version of your template

Scenario 2.b: no updated version available

We are looking at scenario 2.b, as all other scenarios are straightforward to solve (with your template developer). A warning upfront: this is going to be rather hands-on and technical (you need to change things in the database and in the PHP code of your template), so if you are not familiar with code or databases, you might want to get some professional help. Make sure you have a backup to revert to when things go wrong, and if you don’t know how to do that, have a backup person stand-by who can help you.

Preparation

Create a new Joomla 4 Test Site, so you don’t break your actual site, which should still be on Joomla 3.10. Use the same database table prefix as for your J3 site.

Activate the Joomla 'Debugging', see this blogpost on how to do that: https://www.joomdev.com/blog/entry/how-to-enable-debug-and-error-reporting

Copy the '/templates/YOURTEMPLATE/' directory from your J3 site to your J4-Test Site

Backup your complete J3 website database into a local file on your computer, see the documentation on how to do that (scroll to the part called ‘Database backup’: https://docs.joomla.org/Backup_Basics_for_a_Joomla!_Web_Site

Prepare for inserting the database records

You have to insert TWO database records from your J3 database into your J4-Test database, and you need to make some small changes to these two records:

Open your downloaded file in an editor like Notepad or a code editor. Find the '#__extensions' database table (where '#__' stands for your actual database table prefix).
Find the 'INSERT INTO #__extensions' part, with YOURTEMPLATE data line - it will look something like the one below - and copy it into an empty Notepad or code editor file: first the part from INSERT INTO to VALUES, and after that the part that applies to your template.

This is what the first part should look like:

INSERT INTO `#__extensions` (`extension_id`, `package_id`, `name`, `type`, `element`, `folder`, `client_id`, `enabled`, `access`, `protected`, `manifest_cache`, `params`, `custom_data`, `system_data`, `checked_out`, `checked_out_time`, `ordering`, `state`) VALUES

This is what the second part should look like:

(10007, 0, 'YOURTEMPLATE', 'template', 'YOURTEMPLATE', '', 0, 1, 1, 0, '{\"name\":\"YOURTEMPLATE\",\"type\":\"template\",\"creationDate\":\"01.01.2000\",……………..,\"filename\":\"templateDetails\"}', '{\"template_width\":\"1400\",\"body_color\":\"#ffffff\",…………….,\"bottom_modules_switch\":\"1\",\"base_modules_switch\":\"1\"}', '', '', 0, '0000-00-00 00:00:00', 0, 0);

The idea is you paste both parts below each other so you have one statement; the first part contains information on where to store the data, and the second part on what data need to be stored.

IMPORTANT: Joomla 4 no longer has the 'system_data' field in this table, so you need to delete this from your INSERT statement – we marked this (both the FIELD NAME and the EMPTY VALUE) here in yellow in the example. Make sure you also remove the respective COLONs.

Find the '#__template_styles' database table (where '#__' stands for your actual database table prefix.
Find the 'INSERT INTO #__template_styles' part, with YOURTEMPLATE data line - it will look something like the one below - and copy it into an empty Notepad or code editor file, like you did in the previous step.

This is what the first part should look like:

INSERT INTO `#__template_styles` (`id`, `template`, `client_id`, `home`, `title`, `params`, `inheritable`, `parent`) VALUES

This is what the second part should look like:

(9, 'YOURTEMPLATE', 0, '1', 'YOURTEMPLATE - Standard', '{\"template_width\":\"1200\",………….. "base_modules_switch\":\"0\"}', 0, '');

The idea is you paste both parts below each other so you have one statement; the first part contains information on where to store the data, and the second part on what data need to be stored.

Now you have two INSERT statements.

Now submit these two INSERT INTO rows with phpMyAdmin into your Joomla 4-Test database.

Use your template on the J4-Test website

Make sure ONLY your template is selected as 'Default'. You might have to deselect the Cassiopeia template to achieve this.

Create some content for your J4-Test Site, like a few articles and a menu structure resembling your actual website. This should allow you to find the most common issues in your template.

NOW you are ready to fix any issues Joomla 4 might have with your template! We list the most common issues and how to get rid of them in the following part… but you might come across yet other issues, so please comment below on any findings you have.

Additional plugins/frameworks for your template

Your template may need additional elements (outside the “templates/YOURTEMPLATE” directory) such as libraries or plugins. You notice this, if the error messages you see do not refer to your template directory, but somewhere else.

Basically the steps to J4-ify these elements are similar to those for your template

copy the respective directories from your J3 site to your J4-Test Site
find and INSERT the respective database records in the '#__extensions' database table (probably no other database table needed)
fix the issues you come across the same way as you do for your template (see the following chapters)

Behaviour Framework not found

To fix this error, look at the 'Call Stack' for the first occurence of 'YOURTEMPLATE' (whatever you called your template of course). In our example this is 'index.php' in your template directory, and the error occurs on line 12 of that file. Open that file in a plain-text editor. On line 12 you will find something like:

JHtml::_('behavior.framework', true);

You can fix this error the following way by 'ignoring' this line :

/*** JHtml::_('behavior.framework', true); ***/

Cannot access protected property …. ::$params

To fix this error, look at the line of the 'Call Stack'. In our example this is 'class.menu.php' in a system plugin called 'STOOLS' (which is needed for the template in our example), and the error occurs on line 65 of that file. Open that file in a plain-text editor. On line 65 you will find something like:

… xyz->params ….

You can fix this error by calling the function 'getParams()' instead of the property 'params':

… xyz->getParams()

Class JSite not found

To fix this error, look at the line of the 'Call Stack'. In our example this is 'class.menu.php' in a system plugin called 'STOOLS' (which is needed for the template in our example), and the error occurs on line 170 of that file. Open that file in a plain-text editor. On line 170 you will find something like:

… $router = JSite::getRouter();

You can fix this error by renaming the 'JSite' part to 'JApplicationSite' :

… $router = JApplicationSite::getRouter();

Call to undefined method isSite / isAdmin

Call to undefined method Joomla\CMS\Application\SiteApplication::isSite()

Call to undefined method Joomla\CMS\Application\SiteApplication::isAdmin()

To fix this error, look at the line of the 'Call Stack'. In our example this is 'system.php' in a template framework called 'WARP' (which is needed for the template in our example), and the error occurs on line 86 of that file. Open that file in a plain-text editor. On line 86 you will find something like::

… isSite()

…isAdmin()

You can fix this error by renaming the 'isWhichone()' part to 'isClient('whichone')' :

… isClient('site')

… isClient('administrator')

Undefined property: stdClass::$catslug

To fix this error, open the file referenced in the error message in a plain-text editor. On the line referenced in the error message you will find something like:

… $this->item->catslug…

You can fix this error by renaming the 'catslug' part to 'catid' :

… $this->item->catid…

Copy your changes back to your Joomla 3 site

Once you are sufficiently satisfied that all Joomla 4 issues are solved in your J4-Test Site, you can transfer all changes back to your real website.

take your J3 website into maintenance mode, see here on how to do that: https://docs.joomla.org/Taking_the_website_temporarily_offline
Ensure yourself all other extensions are Joomla 4 compatible by checking the Pre-Update Checker.
IMPORTANT: make another complete backup of your Joomla 3 website! The next steps you take could break your site (although of course you’ve checked your extensions, but still, better safe than sorry)!
Copy the '/templates/YOURTEMPLATE/' directory from your J4-Test Site to your J3 site.
Check your website (since you’re in maintenance mode, you’d have to login first) to make sure everything is working correctly. If not, then
find the issue, and maybe you have to revert that change you made (and only make it later again, when you actually migrate to Joomla 4).
Switch the maintenance mode to OFF

Yet another warning here: if your website heavily depends on third party extensions (like webshops, eventbooking, community tools and whatnot), your template might have similar issues in connection with these extensions. So keep track of what you had to change in the template, in order to make similar changes to your template regarding these third party extensions, once you migrated to Joomla 4.

You now can answer “YES, probably” to the question: is your template ready for Joomla 4?

Conclusion

If your Joomla website has been up and running for several years now, chances are your current template will not be compatible with Joomla 4. If you decide to keep your template and need to manually fix any upcoming problems with this, I here provided solutions for a number of common issues you might have.

There may be a substantial number of issues for Joomla 4 with your old Joomla 3 template, but I believe that with this article and the relevant software developer skills available to you, most of them should be solvable. Indeed it will require some ressources, and you need to consider whether the effort is justified, or you better should embrace the future and use a modern J4 template right away.

Once everything on your website looks Joomla 4 ready, you can plan for the actual migration of your website towards Joomla 4. But as a general rule, you should allow enough time to fix any further issues that might arise on your new Joomla 4 website - this migration is much more than a simple update (e.g. from Joomla 3.10.1 to 3.10.2).

Further resources

Most solutions here were found by ‘educated Google searching’, but the Joomla 4 backward compatibility issues blogpost is a good source as well:

https://docs.joomla.org/Potential_backward_compatibility_issues_in_Joomla_4

Vous êtes: développeur joomla, graphiste
Auteur.e: Ruediger Schultz
Source: https://magazine.joomla.org/all-issues/october-2021/how-to-j4-ify-your-old-joomla-3-template
Langue initiale: Oui