Support

Documentation

Customising the frontend layout

Akeeba Ticket System has a simple, clean design using either Bootstrap 5 or a custom CSS file. To make things simpler for site integrators we only use vanilla JavaScript, without relying on jQuery or any other framework, and core Joomla features thus minimising the need to rework our component when using different templates. We also provide an abundance of custom module positions to allow site integrators to put additional information in Akeeba Ticket System pages beyond what the template they are using allows them to do.

While this is all great and flexible, we understand that there's no such thing as one–size–fits–all in web design. One of the greatest strengths of Joomla over any other PHP–based CMS is that it allows site integrators to easily customise the frontend experience with overrides. ATS is a native Joomla component and of course supports all of these overrides without much effort. Even better, we designed ATS expecting overrides to take place and made sure to provide features to help you towards that goal such as plenty of CSS classes and even the source SCSS files for our custom frontend CSS.

In this section we will discuss all the ways you can use to customise the look and feel of the frontend.

Component view template overrides

The ATS component's frontend is primarily generated by standard view template files. These are the PHP files in the subdirectories of the components/com_ats/tmpl folder under your site's root. You can override them as explained in the official Joomla documentation page on overriding the output from the Joomla! core.

Some other parts of its output are generated through Layouts. These are PHP files in the subdirectories of the components/com_ats/layouts folder under your site's root. These typically are reusable and smaller pieces of content display. They are called by the view template files using the LayoutHelper helper class provided by Joomla. Overriding them is similar to overriding view templates and discussed in the Layout overrides section below.

But let's go back to the view templates. Joomla offers two ways to do that.

Using the Joomla Template Manager

This method is discussed in the Joomla documentation.

Go to System, Templates, Site Templates.

Select your site's template.

Click on the Create Overrides tab.

From the Components area click on com_ats. You can now select the view whose files you want to override. For example, selecting ticket will override the Ticket view which is used when creating a new ticket and when viewing or editing an existing ticket.

Back to the Editor tab, navigate to html then com_ats. You will see a new directory with the same name as the one you selected on the step above. Clicking on it you can see all the files Joomla copied over from our component and you can edit them.

These are your own copy of our view template files, living inside your site's template. You can modify them freely without fear of breaking ATS. If you mess up you can delete these files (or the entire subfolder) and start over.

Copying files manually

The Joomla template manager doesn't perform any magic; it simply copies over files. You can copy the files manually and edit them in a programmer's text editor (e.g. Notepad++ on Windows, gEdit or Kate on Linux, or BBEdit on macOS) or a full blown IDE such as Visual Studio Code, NetBeans, Eclipse, phpStorm etc.

You will only need to know where your site's template lives inside your site's filesystem. All templates live under the templates folder in your site's root. Inspect the subfolders there to find out which one has your template. In this documentation we will call that subfolder MY_TEMPLATE.

Go to the folder components/com_ats/tmpl and find the subfolder of the view and which file(s) you want to override. Yes, that's right, you DO NOT need to copy all files; you only need to copy the ones you actually want to override.

Let's say that you want to override components/com_ats/tmpl/ticket/default_post.php.

  1. Create the subfolder templates/MY_TEMPLATE/html/com_ats/ticket You may have to create parent folders to get there.

  2. Copy the file components/com_ats/tmpl/ticket/default_post.php to templates/MY_TEMPLATE/html/com_ats/ticket/default_post.php

You can now edit the file templates/MY_TEMPLATE/html/com_ats/ticket and customise it as you wish. It will be used INSTEAD OF the file we provide with ATS.

Custom fields in view template overrides

All of our views run the displayed items through Joomla's content plugins. This means that the category and ticket objects made available in our view templates will have the jcfields property containing the custom fields as long as the core Joomla Content - Fields plugin is published. Please remember that publishing this plugin and having its Access set to Public is a hard requirement by Joomla itself. This is the plugin which runs the core Joomla code to make custom fields available to any extension, be it a core Joomla extension such as Articles or a third party extension such as Akeeba Ticket System. In fact, the jcfields property is created and populated by this plugin. Our code has NOTHING to do with it at all; that's how Joomla is designed to work and we follow the Joomla best practices to the fullest extent.

By default, the jcfields property is an array ordered by the numeric field ID which is not particularly helpful. As explained in the Category custom fields and Ticket custom fields sections you can use the getFieldsByName helper in your template overrides to get an array sorted by the field's name (the alias, not the label!).

Please keep in mind when using the helper that your field names must be unique across all field groups. Otherwise it's hard to tell which field will be returned by the helper. Technically, it's the last field that Joomla knows about by this name. However the order by which Joomla will list fields so as to figure out which one is the last one depends on too many factors to make it ever remotely predictable. As we said, use unique names or you'll have troubles nobody can help you with.

Layout overrides

Layout overrides are similar to template overrides. The only thing that changes is the directory they are copied from. Joomla offers two ways to do that.

Using the Joomla Template Manager

This method is discussed in the Joomla documentation.

Go to System, Templates, Site Templates.

Select your site's template.

Click on the Create Overrides tab.

From the Layouts area click on com_ats. You can now select the layout subfolder whose files you want to override. For example, selecting akeeba will override the layouts we use for rendering small pieces of information such as the user's avatar.

Back to the Editor tab, navigate to html then layouts. You will see a new directory with the same name as the one you selected on the step above. Clicking on it you can see all the files Joomla copied over from our component and you can edit them.

These are your own copy of our layout template files, living inside your site's template. You can modify them freely without fear of breaking ATS. If you mess up you can delete these files (or the entire subfolder) and start over.

Copying files manually

The Joomla template manager doesn't perform any magic; it simply copies over files. You can copy the files manually and edit them in a programmer's text editor (e.g. Notepad++ on Windows, gEdit or Kate on Linux, or BBEdit on macOS) or a full blown IDE such as Visual Studio Code, NetBeans, Eclipse, phpStorm etc.

You will only need to know where your site's template lives inside your site's filesystem. All templates live under the templates folder in your site's root. Inspect the subfolders there to find out which one has your template. In this documentation we will call that subfolder MY_TEMPLATE.

Go to the folder components/com_ats/layouts and find the subfolder and file(s) you want to override. Yes, that's right, you DO NOT need to copy all files; you only need to copy the ones you actually want to override.

Let's say that you want to override components/com_ats/layouts/akeeba/ats/common/user.php.

  1. Create the subfolder templates/MY_TEMPLATE/html/layouts/akeeba/ats/common You may have to create parent folders to get there.

  2. Copy the file components/com_ats/layouts/akeeba/ats/common/user.php to templates/MY_TEMPLATE/html/layouts/akeeba/ats/common/user.php

You can now edit the file templates/MY_TEMPLATE/html/layouts/akeeba/ats/common/user.php and customise it as you wish. It will be used INSTEAD OF the file we provide with ATS.