Esentialist
Learning to Learn One Mistake at a Time

How to Create a Joomla 4 Template

The recent update from the folks over at Joomla! requires you to update the files and folders for your site template. Here are my findings on the subject, including a quick download to my custom template, for conveniency's sake.

This guide is in progress. Use at your own risk! These resources are for personal references first, and I claim no expertise, know-how, accuracy, intelligence, or anything else of the kind.

Template Structure

Folders in root directory of your template

  1. "css" folder is where css files are stored
  2. "html" folder is where template overrides are stored
  3. "js" foder is where javascript files are stored

Files in respective folders

  • Files to be added to the root directory folder:
    • "index.php" : the starting and main file of your template.
    • "component.php" : a shorter version of the index.php file. We use it to select what is the main content of the template, without all the bells and whistles. The component.php file is often used to display articles in popup windows, for example.
    • "templateDetails.xml" : manages the installation and options.
    • "joomla.asset.json" : organizes and points to your css files.
    • "template_preview.png" : a 600x400px png for your template image.
    • "template_thumbnail.png" : a 225x150px png for your template preview.
  • Files to be added to the css folder:
    • custom1.css : a css file
    • custom2.css : another css file
  • Files to be added to the "js" folder:
    • "scripts.js" : a file for your javascript
  • Files to be added to the "html"
    • leave empty - files and folders will automatically be stored there by Joomla! when creating template overrides through the admin panel

Step by Step Guide

Create a template from scratch.

  1. In the "templates" folder of your Joomla! installation, create a folder labeled after your template's name using a string without spaces or special characters.
  2. In your template folder, create the files listed above (see template file structure).
  3. Open "index.php" and copy paste this code.
  4. Open "component.php" and copy paste this code.
  5. Open "templateDetails.xml" and copy paste this code.
  6. Open "joomla.asset.json" and copy paste this code.
  7. Open template images "template_preview.png" and "template_thumbnail.png" with Adobe Photoshop and design your template cover.
  8. Replace both images as PNGs in the root directory of your template folder.
  9. In your template folder, create a subfolder labeled "css" and a subfolder label "js."
  10. In your "css" folder, create two files. We named ours "custom1.css" and "custom2.css".
  11. In your "js" folder, create a file. We named ours "scripts.js."
  12. Use the "Discover" function in your Joomla! administrative panel to find and install the template.
  13. Set it as the default template of your website.

Troubleshooting

Option to Force HTTPS breaks administrative template link to CSS

Details : Whether I force the redirect through the Global Configurations or straight through the .htaccess file, domain.com/administrator breaks. The html file can't link to its respective css, and the pages display without any style or formatting.

Solution : Comment out or remove the following the code following this text in your .htaccess file:

## These directives are only enabled if the Apache mod_headers module is enabled.
## This section will check if a .gz file exists and if so will stream it
## directly or fallback to gzip any asset on the fly
## If your site starts to look strange after enabling this, and you see
## ERR_CONTENT_DECODING_FAILED in your browser console network tab,
## then your server is already gzipping css and js files and you don't need this ## block enabled in your .htaccess