Skip to content

Instantly share code, notes, and snippets.

@dgrammatiko

dgrammatiko/child-templates.md

Created November 4, 2021 18:50
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save dgrammatiko/7aa31a2e7f82b9878eb35f8bc7e1203b to your computer and use it in GitHub Desktop.
Save dgrammatiko/7aa31a2e7f82b9878eb35f8bc7e1203b to your computer and use it in GitHub Desktop.
Download ZIP
Raw
child-templates.md

Joomla Child Templates

Joomla 4.1 will support templates with the ability to create child template. Actually the code already exists since 4.0 and this Pull Request. The UI was missing anything meaningful prior to 4.1 so although the new mode technically was supported it wasn't exposed to the end users. The missing UI part will be introduced with Pull Request.

So, what are child templates?

Child templates basically are templates with only one file: templateDetails.xml.

How do they work?

A child template has one field named parent in the templateDetails.xml that holds the name of the parent template, eg: <parent>cassiopeia</parent>. The MVC part of Joomla is already aware how to handle child templates and it works based on inherritability. Eg if index.php doesn't exist in the child the parent one will be used. This pattern is applied to the direct entry points of the template the overrides and also the static file overrides.

Can any template have child templates?

No, the feature is opt-in, so a template in order to be enabled for child templates should have a field name inheritable with a value 1 in the templateDetails.xml. On top of that the static assets are expected to be stored in the media folder rather than the template folder. There is a converter that aims to convert templates with very little effort: https://github.com/dgrammatiko/convert-template

Are there any gothchas we should be aware?

Depends on your actual code, but here's a list of possible ones:

  • Static assets with template relative paths: eg $path = $this->baseurl . '/templates/' . $this->template . '/images/logos/brand-large.svg'; should be written as 'media/templates/administrator/atum/images/logos/brand-large.svg';
  • PHP includes shouldn't use the template name from the variable $this->template for the path so the child could load the correct file: eg include JPATH_ADMINISTRATOR . '/templates/' . $this->template . '/base.php'; should be written as include JPATH_ADMINISTRATOR . '/templates/admin2021/base.php';

Are there any Breacking Changes?

The project will try it's best to keep maximum backwards compatibility. That said the template file editor is expected to have some significant changes so if you have functionality that extends that view please be aware.

Why should someone embrase the child templates?

The idea behind the child templates was to enable template updates without breaking any user modified files. In essence this means a safer environment for the template authors but also for the end users.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment