Joomla Has a Mystery “ordering” Form Field Type

Yesterday evening (or very early in the morning today), we updated the Joomla website of a new client from Joomla 3.1.5 to Joomla 3.7.5 (we are waiting for 3.8.2 to be released to update to 3.8). The update was really nothing out of the ordinary: we did see some issues but we fixed them immediately as all of these issues were déjà vu. We were going to email the client and tell them that we were done, but, as we were about to do that, we noticed a weird error on a custom component, which was more or less like the core Joomla content component, but, it had departments instead of articles. The problem was that when we clicked on a department to edit it (or when we tried to create a new department), we saw the following error:

You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near ‘WHERE `catid` = 0 ORDER BY ordering’ at line 3

We analyzed the view, and we were able to narrow down the problem to the following field in the department.xml file under the administrator/components/com_department/models/forms folder:

<field
	name="ordering"
	type="ordering"
	class="inputbox"
	label="JFIELD_ORDERING_LABEL"
	description="JFIELD_ORDERING_DESC"
/>

Naturally, we searched for the form field of type ordering defined at the component level, and we found it, but we didn’t find any mention of catid anywhere in the extension, so the fatal query wasn’t coming from that field. Strangely though, when we removed the field from the XML file, everything worked as it should (but, of course, without the ordering).

So, we enabled debugging in the global configuration of the Joomla website by setting the value of Debug System to “Yes” under System -> Global Configuration -> System. We then loaded the page and we immediately discovered the cause of the problem: the ordering field was being loaded from another location. It was being loaded from the ordering.php core file which is located under the libraries/cms/form/field folder (note that in Joomla 3.8+, the ordering field is located in the OrderingField.php file, which in turn is located under the libraries/src/Form/Field folder). But, what is that field? And why isn’t documented on the Joomla official website?

Further investigation revealed that this field was introduced in Joomla 3.2.0, and that it is used in 3 extensions: com_banners, com_contact, and com_newsfeeds (by the way, we just noticed, why doesn’t Joomla have some standard when it comes to singular/plural naming in its core extensions; why isn’t com_banner and com_newsfeed instead of com_banners and com_newsfeeds?). The core ordering field does exactly what you expect it to do: it displays a drop down of all the content items belonging to the category of the current content item, which allows you to set the latter’s ordering. The field expects the category name of the current content item to be called catid. If it doesn’t find such field, then it crashes, which fully explains the problem that we were having on the client’s site.

Here’s an example usage of the ordering field from the com_banners extension:

<field
	name="ordering"
	type="ordering"
	label="JFIELD_ORDERING_LABEL"
	description="JFIELD_ORDERING_DESC"
	table="#__banners"
/>

You can see that all that you need to pass as a parameter is the table field, which is #__banners in the case of the com_banners extension (note that in previous versions, such as Joomla 3.2.0, you needed to pass the content_type, such as com_banners.banner).

But why wasn’t the “ordering” Joomla form field type documented?

We’re not really sure but we think it was just that the Joomla documentation team forgot about it (we will report this omission to the Joomla core team) – this is plausible because Joomla officially added a whopping 8 fields in Joomla 3.2 (so the ninth one could have easily fell through the cracks). It might also be due to the fact that this field type feels unfinished and non-generic. For example, why is catid hardcoded in the field? Still, the ordering field has its merits, especially for extensions taking advantage of the #__content and the #__categories tables.

So, what did we do to fix the problem?

We fixed the problem by appending the word department to every instance of the word ordering for that field type. Here’s how:

  • We renamed the file ordering.php which is located under the administrator/components/com_department/models/fields to departmentordering.php.

  • We then opened the departmentordering.php file, and we changed the following line:

    class JFormFieldOrdering extends JFormField

    to:

    class JFormFieldDepartmentOrdering extends JFormField

    We also changed the following line:

    protected $type = 'Ordering';

    to:

    protected $type = 'DepartmentOrdering';

  • Finally, we opened the department.xml file which is located under the administrator/components/com_department/models/forms folder and we changed the following:

    <field
	name="ordering"
	type="ordering"
	class="inputbox"
	label="JFIELD_ORDERING_LABEL"
	description="JFIELD_ORDERING_DESC"
/>

    to:

    <field
	name="ordering"
	type="DepartmentOrdering"
	class="inputbox"
	label="JFIELD_ORDERING_LABEL"
	description="JFIELD_ORDERING_DESC"
/>

Once we did the above, the problem was solved! Woohoo!

Now, if you, our dear reader, are having the same problem and you need help with implementing the solution, then fear not, we are your Joomla super heroes! Just contact us and we’ll fix your website quickly, professionally, and affordably!

No comments yet.

Leave a comment