Support

Documentation

Custom fields

One of the most powerful and most underrated features in Joomla is the support for fields a.k.a. “custom fields”. We strongly believe that Fields together with view template overrides are THE killer features in Joomla. We have been able to implement features on our site which previously required creating custom extensions using just core features. We have seen incredibly complex sites — even one which was essentially a mobile, touch–first showcase application — being realised with nothing more than core Joomla, custom fields and relatively simple view template overrides.

In a nutshell, the Joomla Fields feature allows you to extend content types in core Joomla and third party extensions, like Akeeba Ticket System, adding fields with additional information. The field content can be automatically displayed in a rather clumsy way or used in the code of view template overrides to provide functionality not envisioned in the core or third party component itself. Fields can be locked for editing or display to certain user groups and even limited for editing only in the backend, only in the frontend, or both.

Naturally, Akeeba Ticket System offers full integration with Joomla's Fields feature, both in ATS categories and tickets.

For example, you could use custom fields to display videos or image galleries in the description of a ticket category, style a ticket (think about marking a public ticket “important” and rendering it with a standout color scheme to draw attention) or simply request additional information from your clients when filing a ticket without relying on them remembering to type everything in the ticket text — something we all know never worked reliably.

In this section we assume that you have a modicum of familiarity with the Joomla fields feature in general. If not, or if you want to take a deep dive into what's possible with custom fields, we recommend reading the following excellent article series in the Joomla Community Magazine written by Marc Dechèvre:

On top of these resources we are going to demonstrate how to do some really neat tricks in Akeeba Ticket System using custom fields.

Custom fields in Categories

Joomla Fields are fully supported in Akeeba Ticket System categories. You can do pretty much the same things you can do with Joomla Fields in Joomla's content categories — with a twist!

ATS Categories are displayed in two separate use cases:

  • Category View. When you are displaying a list of categories (the main Categories page in Akeeba Ticket System) or the subcategories part of the category display page.

  • Tickets View. When you are listing the tickets of a category.

Depending on the custom fields you are using you may want to only display them in one use case but not the other. For example, you may want to use a custom field to display a gallery of video tutorials at the top of the Tickets View page, helping your clients get help faster without even submitting a ticket.

Akeeba Ticket System categories allow you to select when to display custom fields: Never (you only get to use them in template overrides), Category View, Tickets View or both.

If you want to have different fields displayed in different use cases you will have to do template overrides and set the category's custom fields display option to None. Unfortunately, this display trick can only be implemented per category for all fields, not per each individual field (that's a limitation of how Joomla fields work).

Custom fields in template overrides

If you want to use custom fields in view template overrides just remember that the category has the same jcfields property you get in Joomla core content categories. This property includes the field values of all fields which would be visible to the user regardless of their Automatic Display setting i.e. it includes fields whose Automatic Display is set to Do Not Display.

For those of you implementing view template overrides we have added a handy dandy helper to make your life managing fields much easier. Joomla keys the jcfields array by field ID which is cumbersome and practically unusable — you typically want to get a custom field by name. To help with that we implemented the getFieldsByName helper.

If you have the category in a variable named $cat and you want to get the information for a field called example on this category all you need to do is $exampleField = $this->getFieldsByName($cat, 'example'); . This returns the object with the field information and value. The raw field value is accessible as $exampleField->rawvalue whereas the fully rendered HTML of the field display is accessible as $exampleField->value.

If the field you are looking for does not exist the field helper will return null.

If you want to get the entire jcfields array keyed by the field name instead of the field ID you just need to omit the second parameter. For example: $allFields = $this->getFieldsByName($cat);.

So, if you want to display the rendered version of a field named video only when the custom field with the name showVideo is set to 1 you can do this in your template override:

<?php if ($this->getFieldsByName($cat, 'showVideo')->rawvalue == 1) {
  echo $this->getFieldsByName($cat, 'video')->value;
} ?>

To make it more safe, checking if both fields are defined before using them, you can do the following:

<?php 
$customFields = $this->getFieldsByName($cat);

if (($customFields['showVideo'] ?? null) && ($customFields['video'] ?? null) 
  && $customFields['showVideo']->rawvalue == 1) {
    echo $customFields['video']->value;
} ?>