Infyways Solutions

Joomla Template Override Not Working: Causes and Fixes

Joomla Template Override Not Working: Causes and Fixes hero

Written by

Abhilash Sahoo

in

A Joomla template override is not working when Joomla never loads the PHP file you edited. The usual causes are the wrong html/ folder, a template style that is not the one assigned to the page, a filename of _default.php (a sublayout, not the layout), an alternative layout selected on the menu item or module, plugin HTML that does not live in the component override, or cache still serving the old markup. This is a file that never loaded. If the file used to work and vanished after an update, that is a different article: template override disappeared after an update.

Create Overrides is the safe copy for components and modules. Plugin tmpl is usually copied by hand into html/plg_…. Official map: Layout Overrides in Joomla. User-manual walkthrough: Template Overrides. Put the copy on a child template, not in parent Cassiopeia.

_default.php rejected versus default.php in html/com_content/article

The layout Joomla looks for is default.php. A leading underscore is a sublayout. The assigned template style must be the folder that contains the file.

What you will learn

  • How to prove the override file is the one PHP included
  • Why Create Overrides for com_ and mod_ is safer than a hand-made path
  • Why plugin HTML is usually html/plg_…, not the article default.php
  • Why _default.php never replaces default.php
  • What an alternative layout on the menu item actually selects
  • Why cache and the wrong template style look like a “dead” override
What you see Likely cause Wrong rabbit hole
Stock markup, your PHP comment missing Wrong folder, wrong template style, or _default.php Editing components/
Override works on Home, not on a landing page That menu item uses another template style Recreating the override
Article body changed, Prev/Next did not Page navigation is a plugin layout More com_content PHP
Blog looks stock, single article changed You overrode article/default.php. The blog uses articles/… (or blog.php) Cache only
File on disk, still stock Alternative layout selected, or cache Reinstalling the component
Child looks stock Override still sits in parent html/ “Overrides are broken”

Step 1: Prove which template is assigned, then prove the file is included

Overrides are files on a template. They are not a Global Configuration switch.

  1. Open the public URL that should use the override.
  2. System → Site Template Styles. Note the default (star).
  3. Open that menu item. Template Style may be a different style (child vs parent, or a club template).

If the page uses cassiopeia_brand and you edited templates/cassiopeia/html/…, Joomla will not load your copy. Child html/ wins for that style. Parent Cassiopeia html/ is unused when the child is assigned. The reverse is also true: assign the parent, and the child’s override is ignored.

Prove inclusion:

  1. On the file you believe is active, add a unique class on a wrapper you already have, for example js-override-probe. Do not use a core-edit in components/.
  2. System → Maintenance → Clear Cache. Test logged out if Page Cache is on.
  3. View Source. Search for js-override-probe.

If the class is missing, Joomla did not include that file. Keep going. If the class is present and the page still “looks stock,” you changed the wrong markup, or CSS is hiding it: Joomla CSS changes not showing.

Step 2: Use Create Overrides for components and modules

Hand-built folders are how silent misses happen.

  1. System → Templates → Site Templates → open the active template (the child).
  2. Open Create Overrides.
  3. Pick the component view (com_content → article, category, …) or the module (mod_login, mod_menu, …).
  4. Joomla copies into templates/{template}/html/com_… or html/mod_….
  5. Edit that copy only.

Typical paths:

  • Article: templates/{child}/html/com_content/article/default.php
  • Category blog: templates/{child}/html/com_content/category/blog.php (and often blog_item.php as a sublayout)
  • Module: templates/{child}/html/mod_login/default.php

Wrong folders that fail silently:

  • html/com_content/articles/ when the view is article (singular) or the reverse
  • html/modules/mod_login/ (extra modules segment)
  • html/com_content/article/tmpl/default.php (no extra tmpl under html)
  • An override on Atum while you are looking at the site

Create Overrides exists so the path matches what Joomla searches. Official folder rules: Layout Overrides in Joomla. Joomla 4 layout notes: Template Layouts.

JLayouts (Read more, images, fields chrome) are not always the view default.php. They live under html/layouts/… after you override them from the Layouts list. If you changed article/default.php and the intro image is still stock, you needed html/layouts/joomla/content/…. The user manual shows the LayoutHelper::render mapping: Template Overrides.

Step 3: Name the file default.php, not _default.php

The layout file is default.php. A leading underscore marks a sublayout. Joomla will not use _default.php as the main view.

Create Overrides copies default.php. Some views also copy default_logout.php, blog_item.php, and similar. Those extra files are included from the main layout ($this->loadTemplate('item') looks for {layout}_item.php). They do not replace default.php.

If you renamed the copy to _default.php because a blog said “underscore means override,” you hid the file from the layout resolver. Rename it back to default.php.

If you only edited blog_item.php while the menu item still uses the default layout (not blog), that sublayout is never included. Match the layout name Joomla is actually rendering (next step).

Step 4: Check Alternative Layout on the menu item, module, or article

Joomla can select a file that is not default.php.

On the menu item: Options (or the Blog / Article tab) → Layout / Alternative Layout. Values such as blog, a template-specific layout, or a custom mylayout.php mean your default.php override is idle for that view.

On a module: Advanced → Alternative Layout. A module can use default.php on one instance and a custom layout on another. You overrode the file the instance is not using.

On an article: some views let the article pick a layout. If that is set, it wins for that article.

Fix:

  • Set Alternative Layout back to default (or inherited), or
  • Create or copy the override with the same basename as the selected layout (blog.php, mylayout.php), still without a leading underscore.

A custom alternative layout is a second file in html/com_…/. It is not a child-template feature by itself. The child only decides which template’s html/ is searched.

Step 5: If the HTML comes from a plugin, do not expect a component override

Content plugins inject markup after (or beside) the component layout. Prev/Next, vote, some field types, and many extra buttons are plugin tmpl files.

Overriding html/com_content/article/default.php will not restyle page navigation. You need html/plg_content_pagenavigation/default.php (and a plugin that actually calls getLayoutPath). Create Overrides usually does not list plugins. You copy tmpl by hand.

Full path, tmpl test, and what cannot be overridden: Joomla plugin override.

If the string is only a label, use a language override instead of PHP.

Step 6: Clear cache, then decide if the file was never going to survive an update

After a path fix:

  1. Clear Cache (and Page Cache for guests).
  2. Hard refresh.
  3. Search View Source for your probe class again.

If the override used to appear and the PHP file is gone from disk after a Joomla or template update, stop this article. You edited the parent. Read template override disappeared after an update.

If the file is still there and still unused, you are still on folder, style, filename, alternative layout, or plugin output.

Keep new overrides on the child so the next Cassiopeia package cannot replace them. Policy: customize without editing core. Visual markup you do not want to maintain: Joomla design services.

Five checks: folder, template style, default.php, alternative layout, plugin output

Folder path, then the assigned style, then default.php versus a sublayout, then Alternative Layout, then plugin HTML. Cache last.

Key takeaways

  1. An override that “does nothing” did not load. Prove it with a probe class in View Source after Clear Cache.
  2. Create Overrides for com_ and mod_ on the active child. Hand-typed folders fail silently.
  3. Plugin output is html/plg_{group}_{element}/, usually manual. Guide: plugin override.
  4. The main file is default.php. _default.php is a sublayout. blog_item.php does not replace blog.php.
  5. Alternative Layout on the menu item or module selects a different basename. Override that file, or set layout back to default.
  6. Child html/ wins only when that child’s style is assigned. Parent and child are not a merge of every PHP file.
  7. JLayouts live under html/layouts/, not always in the view default.php.
  8. A file that vanished from disk after an update is not this diagnosis. Use the disappeared checklist.

Frequently asked questions

Why is my Joomla template override not working?

Joomla is not including that PHP file. The folder does not match the view, the assigned template style is a different template, the file is named _default.php, Alternative Layout points at another basename, or the HTML comes from a plugin. Prove it with a probe class in View Source.

Should the override file be named _default.php?

No. Name it default.php (or blog.php if that is the layout in use). A leading underscore is a sublayout. Create Overrides already uses the correct names.

Why did Create Overrides copy default.php and default_logout.php?

default_logout.php is a sublayout of the login module’s default layout. Edit the file that prints the markup you care about. Deleting default.php when you only wanted logout is correct if you do not want to override the login form. The user manual does exactly that: Template Overrides.

Can I override a plugin from the article layout?

No. Plugin HTML that uses tmpl is overridden under html/plg_…. See Joomla plugin override.

Does a child template automatically use the parent html folder?

No. Same-named files in the child win. Files you never copied stay on the parent. An override that exists only on the parent is unused while the child style is assigned.

I updated Joomla and the override vanished. Is that this article?

No. That is the parent getting restored. Use Joomla template override disappeared after an update.

Where are the official override rules?

Layout Overrides in Joomla and Understanding Output Overrides. Child placement: Child Templates.

Conclusion

When a Joomla template override is not working, stop editing components/ and stop renaming files with a leading underscore. Assign the child style, put default.php (or the alternative layout’s real name) in the matching html/com_ or html/mod_ folder, and treat plugin markup as html/plg_. A probe class in View Source tells you in one reload whether PHP included the file. If the file used to exist and the disk is stock after an update, switch to the disappeared guide and move the work into a child.

Need the markup rebuilt without another silent path? Joomla design services or Joomla support and maintenance.

More posts