Menu
Joomla overrides

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.

What are template overrides?

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.

What is the problem?

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.

Is it then not a BC break?

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.

Is there a solution?

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.

JWC17

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.

overwrite jquery version

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.

How to load jQuery

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

The Problem

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.

The solution

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 :-)

dpcalendar 613 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.

New booking options

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.

Booking form

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.

Booking layout

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.

Booking system

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.

booking options

Hide the events end time

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.

event hide end time

Small improvements and bug fixes

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:

  • [#4078]   Deaktivate parts of booking form
  • [#4913]   date-icons as option in list view
  • [#5144]   Option to not send ICS file in booking mails
  • [#5145]   Option to not send the invoice file in booking mails
  • [#5146]   Option to not send the ticket files in booking mails
  • [#5147]   Disable registration after booking for guests
  • [#5150]   Option for the booking mail body
  • [#5151]   Support custom fields in booking confirmation mail
  • [#5162]   Add options to hide the booking and ticket fields in the layouts
  • [#5176]   Make forms text fields full width
  • [#5173]   Show date before time on timed events
  • [#5120]   Add missing parameters from component from calendar view to mini module
  • [#5127]   Add parameter to not show the event end time
  • [#5143]   Default menu item for events in upcoming module
  • [#5153]   Change order of booking and ticket fields
  • [#5157]   Offer bookings link in event detail page
  • [#5158]   Show custom fields in bookings list
  • [#5160]   Hide ticket form fields
  • [#5165]   Option to disable the booking confirmation mails
  • [#5174]   Price label not displayed
  • [#5096]   Event link not generated correct on Jomsocial wall
  • [#5116]   Render back end views always with BS2
  • [#5117]   Compact mode spans every day till end of month
  • [#5129]   Email button does not open new window
  • [#5133]   Quick Create event form sets wrong date
  • [#5136]   Google Calendar: A location has the same alias on recurring events
  • [#5148]   Event and calendar link in map not correct
  • [#5152]   Editing a booking clears the custom fields
  • [#5167]   Link to calendar date option is not working
  • [#5178]   Map module search box overlaps on small module positions

How to upgrade?

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

jandbeyond 2017

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.

Prepare your extension for Joomla 4

Slides can be found here.

Status New Media Manager

Slides can be found here.

We use cookies on our website. Some of them are essential for the operation of the site, while others help us to improve this site and the user experience (tracking cookies). You can decide for yourself whether you want to allow cookies or not. Please note that if you reject them, you may not be able to use all the functionalities of the site.