j4Starter Template

Start Making Your First Joomla 4 Template!

I have gone through the effort of stripping down the default Joomla 4 Cassiopeia template into just the basics. It includes Bootstrap 5.1, and a very basic Bootstrap grid layout with a sidebar and a few module positions.

This template works with Joomla 4 and is designed to act as a starting point for developers and hobbyists to start building their own custom templates on. I have tried my best to add tons of comments so you know exactly what does what.

If you're unfamiliar with Joomla development, Bootstrap, SASS, or PHP, check out my new guide on developing a custom Joomla 4 template. It provides step by step instructions to create your own Joomla template using j4starter.

Key Features

• Installs with Extension Manager
• Included language files, properly named, so you can edit those
• Set method to update in templateDetails so you can update/install with extension manager
• Many comments to help explain exactly what's going on
• Loads a copy of Bootstrap from the Vendor folder
• Setup for SCSS/SASS so you need a css preprocessor

The default layout of the j4starter template

Download j4Starter

File Structure

j4starter/
|-- html/
|   `-- mod_menu/
|       |-- collapse-default.php
|       |-- default.php
|       |-- default_component.php
|       |-- default_heading.php
|       |-- default_separator.php
|       `-- default_url.php
|-- language/
|   `-- en-GB/
|       |-- tpl_j4starter.ini
|       `-- tpl_j4starter.sys.ini
|-- media/
|   |-- css/
|   |   |-- Notice.txt
|   |   |-- template.min.css
|   |   `-- template.min.css.map
|   |-- images/
|   |   |-- favicon.ico
|   |   |-- template_preview.png
|   |   `-- template_thumbnail.png
|   |-- js/
|   |   |-- template.js
|   |   `-- template.min.js
|   `-- scss/
|       |-- template.scss
|       `-- vendor/
|           `-- bootstrap/
|-- index.php
|-- joomla.asset.json
`-- templateDetails.xml
        

Installation & Use

Just download the zip and install it with the extension manager. You should then be able to go to the templates/j4starter directory and start making changes.

Editing The Template

The most important part of the template, where you can edit the HTML output and PHP used, can be found in the site_root/templates/j4starter directory.

As of Joomla 4.1, the convention has changed to store all template images, js, css, and scss in the MEDIA folder. This means when you install the template, a new folder under your_site_root/media/templates/site/j4starter will be created. All the template media files your template uses will come from here. So if you need to create/edit the CSS, JS, or images your template uses, do so with the files in the media folder.

The same logic applies to the languages folder. Your site uses the files under site_root/language/en-GB when reading language definitions. If you need to make changes to the language files, you must do it there.

Here's a summary of where to find each file after the template's been installed, and what you might need to edit it for.

• /joomla
  • /templates
    • /j4starter
      • index.php - contains the HTML output of the template itself, this is where you may add custom HTML/PHP code to your template
      • joomla.asset.json - contains a list of the template assets (scripts, stylesheets), you will need to edit this file if you change the name of your template or add additional files
      • templateDetails.xml - this is where you can add user configurable template style settings (fields), tell Joomla where your files and folders are, and set details like the template title and author information
  • /language
    • /en-GB
      • tpl_j4starter.ini - your templates language files, where it pulls label text and such from
      • tpl_j4starter.sys.ini
  • /media/templates/site/j4starter
    • /css
      • template.min.css - the final output css file used by the template
    • /images - where you place your templates image files
    • /js - where the templates javascript goes
      • template.min.js - the default js file used in the template
    • /scss - where you can edit the stylesheets, with the help of SASS

Creating an Installable Package

After you've finished editing your template, if you want to install it on another site, or your live site, using the Joomla extension manager, you will have to turn your files back into a zip archive.

To do this, create a new directory somewhere outside of Joomla to work with. We'll call this the package prep folder. This is where we'll prepare our archive. Copy/paste all the files and folders from site_root/templates/j4starter here, as they are. Then, create a media folder within the package prep folder. Copy/paste all the files and folders from your_site_root/media/templates/site/j4starter into the media folder. Finally, create a folder called "language" in the package prep folder, and then a folder called "en-GB" within the language folder. Copy/paste the language files of your template (tpl_j4starter.ini and tpl_j4starter.sys.ini) from site_root/language/en-GB into this folder.

When you're complete, your template archive should look like this:

• my_template_installer.zip
  • index.php
  • joomla.asset.json
  • templateDetails.xml
  • /html
    • *your template overrides*
  • /language
    • /en-GB
      • tpl_j4starter.ini
      • tpl_j4starter.sys.ini
  • /media
    • /css
    • /images
    • /js

Zip the archive. You should now be able to upload and install it on any Joomla 4 powered website. If you experience issues, review your file names, folder structure, and templateDetails.xml file.

A Note on Renaming

As a note, I have used the words j4starter and J4STARTER in every name specific scenario for this template. If you want to rename the template, replace j4starter and J4STARTER with the appropriate name you want to use in all files. As long as you rename appropriately everything should work properly under your new name.

If you're using an editor like Visual Studio Code or WebStorm, you can use the "replace in files" feature to replace all occurrences. Make sure you select the case sensitive option. Eg, if you wanted to name your template "Sam's Template" I'd rename all instances of "j4starter" to "samstemplate" and "J4STARTER" to "SAMSTEMPLATE"

Additional References

Look at the examples in index.php to see the basic layout of the template. All other features may be added through the creation of template overrides, and changes to the CSS and JS. Here are some other resources to check out if you're new to template design or web design.

• Bootstrap 5 - Joomla uses Bootstrap 5, a framework of CSS and JS for its layout, buttons, tabs, popups, etc. If you are not familiar with Bootstrap, I highly recommend you reference the Bootstrap 5 Docs. A good place to start might be learning how to use the Grid to make a layout.
• SASS - To make changes to Bootstrap and your templates files in general, I highly recommend you learn about SASS/SCSS if you do not know it already. This is a css preprocessor that adds extra functionality to stylesheets. Changes should be made to the variables.scss file under the bootstrap directory. Here you can change the primary color, gradients, and many other layout/style features of Bootstrap. SASS is essentially used to take allllllll the stylesheets of Bootstrap and any additional styles you add, then combines them into the single minified/compressed CSS file your template uses.