Have you ever tried to add a custom field to a Joomla module only to find that your override simply doesn't load? It is a common frustration for Joomla developers. You follow the standard procedure: you create a folder in your template's html directory, copy the XML file, and wait for the new fields to appear in the backend. But nothing happens.

In this guide, you will learn why the standard override system doesn't apply to XML files and the professional way to customize module configurations without losing your changes during the next update.

Why Standard Overrides Don't Work for XML

In Joomla, the template override system is designed primarily for layouts. When you place a file in templates/your_template/html/mod_example/default.php, Joomla's output renderer knows to look there first before checking the core module folder.

However, XML files (like mod_example.xml) are manifest files. They define the module's parameters, form fields, and installation metadata. These are processed by the Joomla core (specifically JForm) to generate the administrator interface. Currently, Joomla does not support a native "override" mechanism for these manifest files within the template directory. If you place an XML file in your template's html folder, Joomla simply ignores it.

Since you cannot override the XML file directly, the most stable and professional approach is to "fork" or clone the module. This involves creating a new version of the module with your specific modifications. While it requires a bit more setup, it ensures that your changes are never overwritten by core or third-party updates.

Step 1: Copy the Module Files

Locate the module you want to modify in your public_html/modules/ directory. Copy the entire folder. For example, if you are working with mod_pr_slider, copy the folder and rename it to something unique, like mod_pr_slider_custom.

Step 2: Rename the Manifest and Entry Files

Inside your new folder, you must rename the primary files to match the new folder name: 1. Rename mod_pr_slider.xml to mod_pr_slider_custom.xml. 2. Rename mod_pr_slider.php to mod_pr_slider_custom.php.

Step 3: Update the XML Manifest Content

Open your new .xml file and update the metadata. This is where you will add your custom fields. Ensure you change the name tag so you can distinguish it in the Joomla Module Manager:

<extension type="module" version="3.0" client="site" method="upgrade">
    <name>MOD_PR_SLIDER_CUSTOM</name>
    <author>Your Name</author>
    <creationDate>2023</creationDate>
    <!-- Add your custom fields here -->
    <config>
        <fields name="params">
            <fieldset name="basic">
                <field name="custom_link" type="text" label="Custom Link" />
            </fieldset>
        </fields>
    </config>
</extension>

Step 4: Find and Replace Class Names

To avoid PHP conflicts, you must ensure that your new module doesn't use the same class names or constants as the original. Use a code editor like Visual Studio Code or Sublime Text to perform a "Find and Replace" across the entire new folder:

  • Replace MOD_PR_SLIDER with MOD_PR_SLIDER_CUSTOM
  • Replace mod_pr_slider with mod_pr_slider_custom (pay attention to case sensitivity)
  • If there is a helper class (e.g., ModPrSliderHelper), rename it to ModPrSliderCustomHelper in both the file name and the class declaration.

You could technically edit the original XML file located in modules/mod_pr_slider/mod_pr_service.xml.

Warning: This is highly discouraged. The next time you update that module or the Joomla core, your changes will be wiped out. Only use this for temporary testing or if you are certain the module will never be updated again.

Best Practices for Module Customization

When forking a module, keep these best practices in mind to maintain a healthy CMS:

  1. Check the License: Most Joomla modules are GPL, meaning you are free to fork them, but always verify the developer's license before redistributing.
  2. Language Strings: If you don't want to recreate all language files, you can keep the original language constants (e.g., MOD_PR_SLIDER_TITLE), and Joomla will still pull them from the original language files if they are installed.
  3. Update Servers: Remove any <updateservers> tags from your new XML file. If you leave them in, Joomla might try to "update" your custom module back to the original version.

Frequently Asked Questions

Can I use a System Plugin to modify the XML form?

Yes. For advanced developers, a System Plugin using the onContentPrepareForm event can inject fields into a module's XML form dynamically. This is a "cleaner" way as it doesn't require cloning the module, but it requires significant PHP knowledge.

Does Joomla 4 or 5 support XML overrides?

As of the current versions, Joomla still focuses the template html override system on the layout .php files. The manifest XML remains the authoritative source for the module structure and is not overridable via the template.

Wrapping Up

While it is frustrating that you cannot simply drop an XML file into your template's override folder, cloning the module is a robust solution. It gives you full control over the fields, the logic, and the styling without the risk of losing your work during a site update. By following the naming conventions and updating the manifest correctly, you can extend any Joomla module to fit your specific project needs.