Joomla 4 templating is more powerful than Joomla 3. But it can be confusing at first because some template files will be stored in the
/media/templates/site folder to make use of the Web Asset Manager. The Web Asset Manager tracks and locates files in the media folder, it can be used for adding file attributes and dependencies and it also applies a cache-busting string to those assets.
This article is the first in a series on Joomla 4 templating for developers. The purpose of these articles is to create and install a functional, but barebones J4 template called
simple. Layout and styling won't be covered in this series. There will be a complete download available in the final article in this series.
Also, I won't be referring to the Cassiopeia template or using the native bootstrap, google fonts, etc that's built in to Joomla. If you would prefer to do it that way, then see this great article by Kevin's Guides instead.
We'll begin with the manifest file
templateDetails.xml which provides the instructions to Joomla as to how to install the template.
The most common reason for failed template installs is basic errors in the templateDetails.xml file. XML is strictly typed, so check the code with an eagle eye!
The Manifest - templateDetails.xml
Since our template is named
simple, we will:
- Create a folder
- Create the manifest file inside that folder:
Here are the contents of templateDetails.xml with some explanations to follow. The line numbers are for explanatory purposes, they shouldn't be included in the actual file itself.
1. <?xml version="1.0" encoding="utf-8"?> 2. <extension type="template" client="site" method="upgrade"> 3. <name>simple</name> 4. <version>1.0</version> 5. <creationDate>01/01/2023</creationDate> 6. <author>Me</author> 7. <authorEmail>
Same for every templateDetails.xml file
Your template name, prefer lowercase
The version number of your template. Here it's 1.0. The next iteration would be 1.1. To update, you would re-install the entire template with 1.1 as the next version number in the templateDetails.xml file.
This is the template description. The placeholder is always in uppercase. It goes into both language files like this (use any description you want really):
TPL_SIMPLE_XML_DESCRIPTION="The Simple Template"
parent are 2 new tags with J4 templating. If you omit the parent tag and have inheritable as 1, then the template qualifies to be a parent since it is also inheritable, as we are doing here. On the other hand a child template must use the parent tag specifying who the parent template is.
simple is a stand-alone template that isn't intended to be a parent or a child template, we omit the
parent tag, but find that we must still include
inheritable with a value of
1, otherwise the required
HTMLHelper functions won't be able to search for images, icons, fonts, assets in the
media folder. Technically
simple qualifies as a parent template, even though she has no intention of every having children!
<files> tag you will add all files and folders that will be installed into the
/templates/simple folder (don't confuse this with the
- component.php (file) - used for Joomla's print function and
- error.php (file) - template for error pages
- index.php (file) - this is the main templating file
- templateDetails.xml (file) - the manifest (instructions) file we are working on here
- joomla.asset.json (file) - instructions for the Web Asset Manager, includes a list of files in the media folder for tracking
- html (folder) - used for override files of Joomla modules/layouts and plugins
- language (folder) - see below and also the next article in the series
Notice that I also included the folder:
language. This is because I like to keep the languages files inside my
/templates/simple folder. This is different to the normal instruction which you can see in lines 26-29. I won't be using those lines. If you decide to use lines 26-29 then omit the
language folder from the
<files> tags. It's one or the other, not both! If you use lines 26-29, then your language files will get stored in the main Joomla languages folder as in:
- /languages/en-GB/ tpl_simple.sys.ini
In previous versions of Joomla that meant that your language files did not upgrade even if you upgraded your template. However if you keep the language files in your
/templates/simple folder, they will upgrade perfectly on a re-install.
These are the files and folders that are going to be put into the
/media/templates/site/simple folder. They are put here so we can use the Web Asset Manager to track them and/or add a cache busting strings. Any file in here will be tracked, but only the ones listed in the
/templates/simple/joomla.asset.json will be given a cache-busting string in it's url. More on that when we take a look at the joomla.asset.json file in a later article.
You could also put a
fonts folder here, if you're locally hosting font files like .woff, .woff2 and so on. I won't be doing that as I'm downloading from Google instead. The folders I'm including here are:
- images (folder) - images for the template
- css (folder) - stylesheets for the template
- scss (folder) - d/l bootstrap scss source files from github and put them here. I'll use dartsass to compile the scss into css for final production. You could also use tailwind or whatever css library you want
images folder - as well as storing your template's svg/png/jpg/webp/etc files, you can also put these two J3 files:
template_thumbnail.png. This is optional, it just gives a template preview in the backend (System - Site Templates). It's also recommended that you include your favicon file(s) in here because you can use Joomla's
HTMLHelper methods to access them from here also.
These are your template positions. Use as many as you like, and name them whatever you like. You'll use these to position modules inside your index.php template file. So if you create a Search module, you might want to add a position like this:
Later on we can use that position to place the search module exactly where we want it in the index.php template like this:
<?php if ($this->countModules('search', true)) : ?> <div class="someclass"> <jdoc:include type="modules" name="search" style="none" /> </div> <?php endif; ?>
These are for your configs which appear as configurable template options in the Joomla backend (System - Site Template Styles - Simple, choose Advanced tab). If you don't have configs, you can omit it, or just use
Note the language string on line 49. The label refers to a language placeholder
TPL_SIMPLE_GOOGLEFONTS that needs to go into your language file. So you'd enter something like this into your
TPL_SIMPLE_GOOGLEFONTS="Please enter the url for your chosen google fonts"
The user could then paste their chosen fonts like:
We will later extract that string into our templating files (index.php, error.php and component.php) and put in the necessary code to have the fonts imported.
This article has dealt with setting up the manifest file:
templateDetails.xml. In order for the
simple template to be installable we'll prepare the file structure as follows:
tpl_simple (folder) templateDetails.xml joomla.asset.json index.php component.php error.php html (folder) language (folder) en-GB (folder) tpl_simple.ini tpl_simple.sys.ini media (folder) css (folder) style.css style.min.css error.css error.min.css js (folder) template.js template.min.js scss (folder) images (folder)
Next in the series, we'll deal with how to set up the language folder for the installable template.