How to override the HTML output of form fields in Joomla 3+

Edited: 03/02/2018

Joomla 3 is a really helpful tool for speedy website development because it provides a great deal of ‘out of the box’ functionality at a few clicks of a button.

However, the HTML output that Joomla generates is often more verbose when compared to hand-written HTML — the multitude of layout options Joomla provides means that a lot of <div> and <span> elements are required to structure content. This is unavoidable and in no way a criticism of Joomla — the additional elements are essential.

It’s useful to know how we can edit the default HTML content Joomla generates. This is particularly useful when making and installing templates.

For example, it is feasible that in making a contact form for the front-facing part of your website, you may want to adjust the HTML generated by PHP statements such as:

<div class=”form-group”>

<?php echo $this->form->getLabel(‘contact_name’); ?>

<?php echo $this->form->getInput(‘contact_name’); ?>

</div>

Below is the default output generated from the default contact form for the field requesting the user provide their name:

<div class=”form-group”>

<label id=”jform_contact_name-lbl” for=”jform_contact_name” class=”hasPopover required” title=”Name” data-content=”Your name.”>Name<span class=”star”>&#160;*</span>

</label>

<input type=”text” name=”jform[contact_name]” id=”jform_contact_name” value=”” class=”required” size=”30" required aria-required=”true” />

</div>

As you can see, Joomla does quite a bit for us already, but there are still quite a few things we might want to edit — for example we might want to apply an additional class name or set a default value or placeholder text.

Override

As you will find mentioned a lot in the Joomla documentation, it is best to create what is termed an ‘override’ rather than edit the core Joomla distribution files. Overriding essentially copies files from the core Joomla distribution to a html folder in your active template directory where you can edit to your heart’s content without damaging the core files.

The word active should be stressed — overrides ‘belong’ with the active template, so when you switch to a different template, without an override, Joomla will load the core files instead.

Overriding is simple. Go to the administrator and select Extensions → Templates → Templates (sub-menu) → then click on your active template.

Select the Create Overrides tab. You will then see three columns. In this case I want to change the output HTML for the contact form so under the layout column, I click on the form link.

This will add a number of files and folders into your template directory at this file path:

joomla/templates/mytemplate/html/layouts/joomla/form

The files / folders are:

  • field/ — contains files for buttons, file input, check-boxes, radio buttons etc

It’s then quite straightforward to edit these .php files to ensure Joomla outputs what you want. However, always be aware of what you remove — if you remove too much you may affect functionality that the administrator might expect to be working in the template.

For example (in renderfield.php):

<div class=”control-group<?php echo $class; ?>”<?php echo $rel; ?>>

<?php if (empty($options[‘hiddenLabel’])) : ?>

<div class=”control-label”><?php echo $label; ?></div>

<?php endif; ?>

<div class=”controls”><?php echo $input; ?></div>

</div>

If I cut out the if statement, when an admin selects the option in the administrator panel to hide the labels for <input> tags, they will find that the option doesn’t work. I’ll edit the HTML down to this.

<?php if (empty($options[‘hiddenLabel’])) : ?>

<?php echo $label; ?>

<?php endif; ?>

<?php echo $input; ?>

The HTML <label> element can be fully edited in the renderlabel.php file.

Bear in mind that any change here is replicated across all <label> elements so if you did want some to render some labels differently, you should think using some PHP here to conditionally add a different CSS class.

It might be tempting to add CSS immediately above in <style> tags however a class name is best — so you do not get into a situation..

However, be careful not to complicate the PHP script too much here.

<label id=”<?php echo $id; ?>” for=”<?php echo $for; ?>” class=”<?php echo implode(‘ ‘, $classes); ?>”<?php echo $title; ?><?php echo $position; ?>>

<?php echo $text; ?>

<?php if ($required) : ?>

<span class=”star”>&#160;*</span>

<?php endif; ?>

</label>

Again, remember if you delete too much, you might break functionality. Best bet is to just edit HTML elements rather than any PHP.

However the renderfield.php file doesn’t allow us to edit the <input> tags that get shown.

So how to we edit the HTML for an <input>?

Contact.xml

We don’t actually need to edit the HTML <input> elements because we can specify all our attributes through the .xml form definition file.

We need to do another override, this time a com_content override since we want to override a <input> element which is part of a contact form.

Again, overriding is simple in this case. Go to the administrator and select Extensions → Templates → Templates (sub-menu) → click on your active template. This time you need to select the com_content link.

This will add a number of files here:

joomla/templates/mytemplate/html/com_contact/contact/

As we are working here on the default form we just need to edit the default.php file. If you open this up and compare against the view source of the HTML form in your browser you will see this is the file that renders the form. (the other .php files are if the contact is displayed according to a category, user profile etc).

When Joomla displays the form it will by default render the inputs that are specified in the joomla core for the com_contact component:

joomla/components/com_contact/models/forms/contact.xml

We need to get Joomla to read from a file we are going to edit.

To do this we need to add the following lines to the default.php file, which instructs Joomla to look for a file in the same folder as the default.php file. (the first line prompts Joomla that it should not read from the default location).

$this->form->reset(true);

$this->form->loadFile(dirname(__FILE__) . ‘/’ . “contact.xml”);

So we now need to copy the forms.xml file from:

joomla/components/com_contact/models/forms/contact.xml

Save it in the folder for your active template:

joomla/templates/mytemplate/html/com_contact/contact/contact.xml

Now just a case of finding the field you want to edit and update the attribute. In this case I added a class name of ‘form-control’

<field

name=”contact_name”

type=”text”

label=”COM_CONTACT_CONTACT_EMAIL_NAME_LABEL”

description=”COM_CONTACT_CONTACT_EMAIL_NAME_DESC”

id=”contact-name”

class=”form-control”

size=”30"

filter=”string”

required=”true”

/>

Remember that it is the PHP statements in the default.php file that renders the form inputs on your website so just adding extra <field> elements to the contact.xml file won’t make these appear on your website.

Joomla! 3 …dissected

Written by

Exploring how Joomla 3+ functions ‘under the hood’ and sharing my own learning of using the powerful Joomla CMS.