Joomla 3 & 4 Compatibility

These are the ways we’ve found to provide extensions that are compatible with both Joomla 3.8+ and Joomla 4.

1. Administration Templates
2. Form Fields
   1. Versioned layouts
   2. Joomla 4 layout attribute
3. Sliders, Tabs, Tooltips and Modals
4. Sortable Tables
   1. Joomla 3
   2. Joomla 4

Administration Templates

We have implemented view classes in our Joomlashack Framework that can choose templates based on the Joomla version. For example, in list views, default.j3.php will be loaded in Joomla 3 while default.php will be loaded by Joomla 4.

Note that subtemplate names for Joomla 3 may seem a bit odd, but do make a certain kind of sense: default.j3_subtemplate.php

Admin view classes should inherit from one of these two framework classes:

• Alledia\Framework\Joomla\View\Admin\AbstractList
• Alledia\Framework\Joomla\View\Admin\AbstractForm

Form Fields

Versioned layouts

If you need versioned layouts for a custom form field, you can add a trait from the framework. For example:

class OsmapFormFieldMenus extends FormField
{
    use \Alledia\Framework\Joomla\Form\Field\TraitLayouts;
    
    protected $layout = 'osmap.menus';
}

This will automatically look for either osmap/menus_j3.php or osmap/menus.php in a layouts folder in the same directory as the class file defining the custom form field.

Joomla 4 layout attribute

Joomla 4 now implements special layouts via the ‘layout’ attribute of the <field> tag. To provide the same behaviors in Joomla 3 and Joomla 4, use the following markup that will work in both Joomlas.

<field type="radio"
       class="btn-group btn-group-yesno"
       layout="joomla.form.field.radio.switcher">
    <option value="0">JNO</option>
    <option value="1">JYES</option>
</field>
            

<field type="list"
       class="chzn-color chzn-color-state form-select-color-state">
    <option value="0">zero text</option>
    <option value="1">one text</option>
    ...
</field>
            

<field type="list"
       layout="joomla.form.field.list-fancy-select"/>
            

<field type="list"
       layout="joomla.form.field.groupedlist-fancy-select"/>
            

Sliders, Tabs, Tooltips and Modals

Sortable Tables

Given an array:

$items = ['ONE', 'TWO', 'THREE', 'FOUR'];

Joomla 3

To initialize the table:

HTMLHelper::_(
    'sortablelist.sortable',
    'table-sort',
    'form-test',
    'asc',
    Joomla\CMS\Uri\Uri::current()
);

For this table markup:

<form id="form-test">
    <table id="table-sort">
        <tbody>
        <?php foreach ($items as $row => $item) : ?>
        <tr sortable-group-id="&lt;ID&gt;">
            <td>
                <span class="sortable-handler">
                    <i class="icon-menu"></i>
                </span>
            </td>
            <td>
                <?php echo $item; ?>
            </td>
        </tr>
        <?php endforeach; ?>
        </tbody>
    </table>
</form>

Notes:

1. sortablelist requires the ajax url for saving order changes. We've used the current url in this example, which would be entirely useless in a real implementation.
2. No additional markup is required in the table beyond the sortable-handler element.
3. Optionally use sortable-group-id="<ID>" attribute on <tr> tags to limit sorting to a subset of the table rows.

Joomla 4

The setup:

HTMLHelper::_('draggablelist.draggable');

The table:

<table>
    <tbody class="js-draggable"
           data-url="&lt;Ajax Ordering url&gt;"
           data-direction="asc"
           data-nested="true">
    <?php foreach ($items as $row => $item) : ?>
    <tr data-draggable-group="&lt;ID&gt;">
        <td>
            <span class="sortable-handler">
                <i class="icon-menu"></i>
            </span>
        </td>
        <td>
            <?php echo $item; ?>
        </td>
    </tr>
    <?php endforeach; ?>
    </tbody>
</table>

Notes:

1. The only markup required to make this work is the addition of js-draggable to the <tbody> element of the table.
2. The sortable-handler element is only needed as a convenience. The entire row becomes the handler.
3. data-url and data-direction are required for saving changes after dropping a moved element
4. data-nested and data-draggable-group are only needed when dragging/sorting need to be limited to a subgroup. e.g. items in the same category.