Joomla 4 Templating. Part 7: Installable Template

In the previous article in this Joomla 4 templating series, we completed coding the template for component.php

In this final article we'll create a zip file: tpl_simple.zip which we can install into Joomla 4.

File and Folder Structure

The file/folder structure for the simple template should now be 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)

Note: you don't need to include the minified styles/javascripts on this install. You can add them manually after the install, when they're ready to go. The Web Asset Manager will always prefer the minified file if it's present, even if it's not specified in your joomla.asset.json. They're scratched out above, because I wouldn't normally put them in until after the install.

Create the installable zip file for the simple template

  1. Open the tpl_simple folder
  2. Compress the files inside the folder to zip format
  3. Your zip file should be named: tpl_simple.zip (or tpl_whateveryourtemplatenameis.zip)

Once you have the installable zip template, log in to the Joomla administrator backend and go to: System-Install-Extensions and upload the file. If all is well, you should see a success message.

To use it, make it the default template. Go to System-Site Template Styles. Choose Simple and make it the default template.

Failed Installs

If the install fails, you'll need to go through the code and check if you have any mistakes. The most common culprit is the templateDetails.xml file. Since it's an XML file, pay attention to closing brackets. Correct the code and try the install again.

If you've any mistakes in the php files, you might also get a failed install. For instance, leaving out a semi-colon at the end of a php statement.

Another common error is that Joomla doesn't like certain folders empty on the install. The html folder is a common culprit because we're not usually going to put anything in here until after the template is installed and we've started coding for component/module/plugin/layout overrides. In this case, you'll see a failed install with a message like:

JInstaller: :Install: File does not exist [ROOT][TMP]/install_63d118120bdcd/html

That means the html folder is empty, so to solve that, put an index.html file into the empty folder with just the following contents:

<!DOCTYPE html><title></title>

Re-zip the template and try the install again.

Downloadable simple template

You can d/l the complete simple template zip here. It's tested on a Joomla 4.4.x with php8.1 install. When it's installed:

  1. Make it the default template (System-Site Template Styles. Select simple and click the Default button)
  2. Compile scss into css (or just add your own style.css into /media/templates/site/simple/css)
  3. Create a test article and add it to the Main Menu (Main Menu-Home. Open Home, change Menu Item type to Single Article, then choose Select Article and choose the test article). This will place that article into the jdoc component position on the home page
  4. You can also paste the url for your chosen Google Fonts (System-Site Template Styles. Open simple, choose Advanced tab). Once they're reference in the stylesheet, you'll see them on the frontend. Example: you choose Poppins 400 and Public Sans 400 and light italic 300. Google gives you some code. The url to paste in is:
    https://fonts.googleapis.com/css2?family=Poppins&family=Public+Sans:ital,wght@0,400;1,300&display=swap

Happy coding!