Customize the form layout with overrides
Visforms implements the improved JLayout Concept by Joomla. Therefore, you can individually overwrite almost every HTML code snippet in the form.
Note: This Joomla feature is extremely cool and extremely flexible. But it's clearly aimed at really advanced users.
Incorrect overrides can break visforms very quickly. Furthermore, after Visforms updates, you must ensure that your overrides are still up to date. Otherwise, the proper functioning of Visforms may be impaired. If we have changed layout files, we issue a corresponding message towards the end of the update process, which draws your attention to this.
The directory for your layout files
Layout files are located in the components/com_visforms/layouts directory. The HTML code of all form fields is generated with the layout files in the directory components/com_visforms/layouts. You can create an override file (a modified copy of the original) for any layout file from this directory under your template directory.
In the following way you adapt the HTML code of the field type individually according to your wishes.
- Create a directory called html in your template if it doesn’t already exist.
- Create a directory in it called layouts if it doesn’t already exist.
- Create a directory com_visforms in it, if this does not already exist.
In this ‘Start’ directory within the template html/layouts/com_visforms, create further directories.
You create the same relative directory structure there as for the original file under the original Visforms ‘Start’ directory components/com_visforms/layouts.
For example, do you want an override file for the original file
components\com_visforms\layoutsvisforms\bt5\multicheckbox\control.php
create an override, the full path is in your template directory
html\layouts\com_visformsvisforms\bt5\multicheckbox\control.php
Which layout files are specifically used?
Which layout files are actually used in your form depends on
- the field type and
- the chosen UI framework.
For the UI framework “None” the files are in the directory
components\com_visforms\layouts\visforms\default
For the UI framework “Bootstrap 5” the files are in the directory
components\com_visforms\layouts\visforms\bt5
For most field types there is a file label.php in which the HTML for the field label is generated separately. And there is a second file control.php in which the actual HTML of the control is generated (e.g. the input element or the select element).
For some field types there is no label.php file. Then either no label is output for this type (e.g. with the field separator) or the label is already part of the control (e.g. with checkboxes in the bootstrap layout). In addition, there are sometimes separate implementations of the HTML code for different UI frameworks.
Separate files do not exist for all field types
Some field types are very similar in terms of the underlying HTML, such as
- text, email,
- Password,
- URL,
- Number,
- Submit button and
- Reset button.
Therefore, these HTML-like controls use one and the same layout file.
Below is a list of the directories where you will find the relevant files depending on the form layout and field type.
Form layouts additionally decorate fields
In some form layouts, fields are embedded in additional HTML tags. Depending on which layout you have chosen for your form, the actual HTML of a form field is additionally packed in additional HTML. For example, for the bootstrap layout, all fields are packed in an enveloping div element and then in additional HTML code.
Each UI framework therefore has its own file in the decorators directory with the task of packing this enveloping HTML around the actual field. For some field types, such as the checkboxes, all HTML code in the Bootstrap layouts is very ‘interwoven’. A clean separation into field and decoration is not possible there.
Depending on the form layout, certain field types cannot be decorated. The corresponding decoration file is then also not called up.
| Field Type | Inherits from | Be Decorated | Directory Name |
|---|---|---|---|
| Text | - | yes | text |
| Text | yes | ||
| Passwort | Text | yes | password |
| Number | Text | yes | number |
| URL | Text | yes | url |
| File Upload | - | yes | file |
| Date | - | yes | date |
| Submit Button | - | no | submit |
| Reset Button | Submit | no | reset |
| Image Submit Button | Submit | no | image |
| Radio Button | - | yes | radio |
| Checkbox Group | Radio Button | yes | multicheckbox |
| Select | - | yes | select |
| Checkbox | - | no | checkbox |
| Textarea | - | yes | textarea |
| Field Separator | - | yes | fieldsep |
| Hidden | - | no | hidden |
Interpretation of the table
The information of the table means the following. Assuming you have selected “Bootstrap 5” as the UI framework and “Custom” as the sublayout. Then first look in the directory components/com_visforms/layouts/visforms/bt5 for a subdirectory with the name of the field type of the field for which you want to overwrite the layout.
If you don’t find this directory here, check whether the selected field type is derived from another field type. If this is the case, check further whether a layout dictionary exists for the field type that was derived from.
If this is not available either, check which form layout type the selected UI framework is derived from. In our example, this would be the UI framework “None”. Then look in the directory of this form layout to see if there is a directory with the name of the field type of the field for which you want to override the layout.
Overrides are done “at your own risk”
All your layout overrides are your own responsibility and “at your own risk”. Visforms comes with a wide range of functions. This wide range of functions is also reflected in the fact that the HTML code is implemented very specifically with regard to the various functionalities.
For example, Visforms relies on certain class attributes and certain style attributes in the code for the “conditional fields” to work. If some of these attributes are no longer available, then Visforms will not work as expected and errors may occur.
Note: Careless layout overrides can easily cause Visforms to stop working as expected.
Caution: We definitely want to offer the possibility to create overrides for users with sufficient knowledge of HTML, CSS, PHP and Joomla. However, we expressly point out that the creation of overrides is entirely "at your own risk" and that we cannot provide free support in this area.