Before we start, Joomla template overrides are a very good tool for site integrators to adapt the core to their needs. But it is a pain for extension developers like us. Why? We will tell you, read on.
Template overrides do require some basic PHP, HTML and CSS knowledge. So it is not a tool for everybody who uses Joomla. It allows site integrators to override the output of any extension in a template. It helps when you have a special requirement which can't be controlled by an option or when you need to change the HTML markup. Basically you can copy the view file (mostly default.php) from the extension view folder to your template html folder. The Joomla view renderer will then automatically pick the one form your template instead of the one from the component. It works for core and 3rd party components, modules, plugins and layouts. More documentation can be found on the web or in the official Joomla docs.
As the view file is a copy of the original file, the problem comes on upgrades. When the original file has changed after an extension is upgraded. For example when new code is added, then the override doesn't get adapted. This can lead to errors or missing features. This is not a problem only for extension developers, also the core is affected. As we introduced custom fields, some templates had an override for the front end article editing form from an old version which was not able to display custom fieldsets in the form. But this are not regular cases in core as new features get added on a much slower pace.
For extension devs it becomes a real problem as we ship new features more often. For example in the release of DPCalendar 6.2, we replaced some javascript libraries with new ones and added the defer attribute to load them faster. All of this happens in the template files (eg. default.php). If you have an override in place, then it still tries to load the old files and can crash your site.
You can argue that it is a BC (backwards compatibility) break. But it is hard to expand BC in layout files, otherwise they will become bloated. It would then also mean that every new feature would require a new major version which would be insane.
Don't do overrides! Wait, really? It is not that dramatically. But you should really consider if an override is needed or if the changes can be done trough CSS as well. We have many customers who want to do overrides, but then we figure out that it is possible to make the changes with CSS commands too. Or we have already an option which does the job. Yes we have a lot of options, so you can control a lot within DPCalendar.
Joomla has a very minimalistic override management UI which doesn't help here much. So what we did, for Google Summer of Code 2018, added a proposal to spice up the override management. Basically you need a diff viewer and an override detector when an extension or the core is upgraded and inform the site owner that layout files have changed where an override exists in the template.
We hope to shed some light into the biggest issue of Joomla overrides.
Allon, the main developer of Digital Peak, was attending the Joomla World Conference to meet the community and share knowledge. It was another great event with amazing people. We are proud and happy to be part of the this awesome community.
As we are part of the Joomla 4 working groud we are very amazed to have released the first alpha version of Joomla 4, the next great thing in the Joomla land. You can read more about it here. Allon was also holding a session about how to convert your Joomla 3 extension to Joomla 4. You can download the slides here.
After telling dozens other extension developers how to correctly load your own version of jQuery in Joomla, we got this week into a conflict with a big community extension. They just load their own copy without care. So it's time to write a blog post how to do it correctly. A side note. In this post we provide very simplified code examples, they should give you a starting point. Please read the Joomla docs carefully and also the Joomla core code itself, that you know what you are doing.
The Joomla CMS comes with it's own unmodified jQuery script in version v1.12.4. When loaded, it executes it in no conflict mode together with jQuery migrate to be compatible with older versions. So every extension which needs jQuery in Joomla MUST load it with the following PHP code. This ensures that the right jQuery script is loaded only once.
JHtml::_('jquery.framework');
More documentation can be found in the official docs.
When you are loading in your extension a jQuery plugin, then you do it mostly that way:
JHtml::_('jquery.framework');
JHtml::_('script', 'com_foo/myJqueryPlugin.js', array('version' => 'auto', 'relative' => true));
JFactory::getDocument()->addScriptDeclaration("jQuery(document).ready(function() {
jQuery('#selector').myJqueryPlugin();
})");
In Joomla are all Javascript files loaded from all extensions before the inline Javascript code. When after your extension is executed another one is loading it's own copy of jQuery like:
JHtml::_('script', 'com_bar/jquery-3.2.1.min.js', array('version' => 'auto', 'relative' => true));
Then the head will look like
<head>
<script src="/media/jui/js/jquery.js?56690c624209a47cb536df0eac0a28f3"></script>
<script src="/media/jui/js/jquery-noconflict.js?56690c624209a47cb536df0eac0a28f3"></script>
<script src="/media/jui/js/jquery-migrate.js?56690c624209a47cb536df0eac0a28f3"></script>
<script src="/com_foo/js/myJqueryPlugin.js"></script>
<script src="/com_bar/js/jquery-3.2.1.min.js"></script>
jQuery(document).ready(function() {
jQuery('#selector').myJqueryPlugin();
})
</head>
This would result in the Javascript error "Function myJqueryPlugin not found". The problem is that the second load of jQuery overwrites the first global jQuery object where the plugin myJqueryPlugin is attached to. So all plugins do not work anymore which are attached to the old jQuery object.
So why this strange way of loading jQuery trough JHtml? It offers the possibility to overload that function in a plugin. What you have to do is to create a Joomla plugin according to the docs for the group system. Then add a function onAfterInitialise and register your own jquery service like in the following code snippet:
public function onAfterInitialise()
{
JHtml::register('jquery.framework', function ($noConflict = true, $debug = null, $migrate = true) {
JHtml::_('script', 'com_bar/jquery-3.2.1.min.js', array('version' => 'auto', 'relative' => true, 'detectDebug' => $debug));
// Check if we are loading in noConflict
if ($noConflict)
{
JHtml::_('script', 'jui/jquery-noconflict.js', array('version' => 'auto', 'relative' => true));
}
// Check if we are loading Migrate
if ($migrate)
{
JHtml::_('script', 'jui/jquery-migrate.min.js', array('version' => 'auto', 'relative' => true, 'detectDebug' => $debug));
}
});
}
This ensures that only your jQuery script is loaded. It reduces the page size as not two jQuery scripts are loaded and it will not break all other jQuery based extensions. The head of your page will then look like:
<head>
<script src="/com_bar/js/jquery-3.2.1.min.js"></script>
<script src="/media/jui/js/jquery-noconflict.js?56690c624209a47cb536df0eac0a28f3"></script>
<script src="/media/jui/js/jquery-migrate.js?56690c624209a47cb536df0eac0a28f3"></script>
<script src="/com_foo/js/myJqueryPlugin.js"></script>
jQuery(document).ready(function() {
jQuery('#selector').myJqueryPlugin();
})
</head>
So we at Digital Peak hope that all extension developers are on the same page and the jQuery errors are history. Time no to turn vanilla :-)
3 months after DPCalendar 6.0 was shipped, which was the biggest version in the era of DPCalendar, we are proud to ship the next update with some amazing new features. Especially the booking system got tons of new options to adjust it to your needs. Additionally a long standing feature to disable the end date can now be defined on a per event level. Read on for detailed explanation of the main features.
Our booking system had already a good amount of functionality and we see an increasing list of web sites, from small to big, which are using it extensively. Appetite comes with eating, so there was demand for more advanced features. And here we go.
The order of the fields can be defined in the booking form, including the custom fields. The fields which are not defined in the order list will be appended automatically. Additionally you can define if the default fields should be required, optional or hidden in the booking form. The name and e-mail field can't be changed as they are required anyway.
The booking layout has similar options as the form. You can define which fields should be shown or not and in which order they should be displayed. Additionally we show the booking custom fields on more places like the confirmation mail or the bookings list.
The booking system allows now fine tuning of the confirmation mails. You can define the body of the mail with the standard Joomla Wysiwyg editor, as default, a language string is used for multilanguage support. And you can define which mail should be sent out with which attachments. Also the invitation to register can be disabled for guest bookings.
Over the years, one of the most requesting feature was to have the possibility to hide the end time of an event. As this is a very difficult task, because DPCalendar offers CalDAV access with a built in server and ical export, an end time is always required. But at the same time we take the feedback of our customers very seriously, so we were looking for a way to support both worlds. There is now a new option when editing an event to hide the end time. You still have to fill an end time, but on DPCalendar in your Joomla site it will be then hidden.
Beside the great new features, we fixed some bugs and added many little goodies to DPCalendar to make your life as administrator easier and to offer your visitors a neat event experience. The following list represents the full changelog of the new 6.1 version:
We tested this version extensively, so you can be safe when upgrading. Just install the whole package from our download site or trough the Joomla update manager, DPCalendar will take care about the rest. As in respect to our backwards compatibility promise, there are no changes in this version which will break your existing layout overrides or require special attention from you.
BUT we recommend always to make a backup first and do the upgrade on a test clone of your production site to have no unexpected downtime. Also clearing the Joomla cache is a good advice when upgrading extensions in general, not just when upgrading the Joomla CMS.
Kind regards
Allon Moritz aka laoneo
Founder of Digital Peak
Allon did attend another great J and Beyond conference, a place where the geeks do meet. He hold two sessions about the new media manager in Joomla 4 and how to migrate your extension to Joomla 4.
Slides can be found here.
Slides can be found here.