Joomla 3 to Joomla 4 Migration: Lessons Learned

3 minutes to read

In migrating a website from Joomla 3 to Joomla 4, there were several gotchas that required modifications to the custom template I had built for a client. All told, the migration went reasonably well, with Joomla’s Pre-Update Check providing the majority of the guidance in terms of incompatible extensions. That said, below I detail some items that required additional attention.

  1. By default, Joomla templates no longer load jQuery. That’s not a bad thing, but for custom templates that require jQuery, you must explicitly load it in the template’s index.php file using the following:
    use Joomla\CMS\HTML\HTMLHelper;
    HTMLHelper::_('jquery.framework');
  2. When setting a Module Class, Joomla 4 automatically appends a space, something Joomla 3 did not do. For example, if you set a Module Class to _foo in Joomla 3, Joomla 3 would render the class as moduletable_foo. Joomla 4 now renders the class as moduletable _foo. This is a distinction that required several updates to the template’s stylesheet.
  3. Specific to Custom modules, the Module Class was not being output in the markup. I had to explicitly set the Module Style to something other than Inherited. The html5 option worked reliably to output the markup as expected, complete with a wrapper div that included the Module Class.
  4. In Joomla 3, when setting a Page Class for a menu item, the class was automatically output in the markup. Not so for Joomla 4. You must explicitly include the Page Class in the template’s index.php file using the following:
    use Joomla\CMS\Factory;
    $app = Factory::getApplication();
    $menu = $app->getMenu();
    $pageclass = $menu->getActive()->getParams()->get('pageclass_sfx');
    Then, you can include the Page Class in your template’s markup as follows:
    <body<?php echo " class=\"$pageclass\""; ?>>