Joomla 4/5 Blank Template – JoomStarter

Formerly j4Starter

Start Making Your First Joomla Template!

I have gone through the effort of creating a very basic Joomla template with extensive commentary. It includes Bootstrap 5.3, and a very basic Bootstrap grid layout with a sidebar and a few module positions. 

I have received many requests to add an option to disable Bootstrap and FontAwesome. This can be easily achieved, but I will not do it by default. For more info read the section on removing Joomla dependencies.

This template works with Joomla 4/5 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  guide on developing a custom Joomla template. It provides step by step instructions to create your own Joomla template using JoomStarter.

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

Download JoomStarter

Full Template Dev Tutorial

Template Dev Videos

Installation & Use

Just download the zip and install it with the extension manager. You should then be able to go to the templates/joomstarter 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/joomstarter 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
    • /joomstarter
      • 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_joomstarter.ini – your templates language files, where it pulls label text and such from
      • tpl_joomstarter.sys.ini
  • /media/templates/site/joomstarter
    • /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_joomstarter.ini
      • tpl_joomstarter.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 joomstarter and JOOMSTARTER in every name specific scenario for this template. If you want to rename the template, replace joomstarter and JOOMSTARTER 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.

On Joomla Dependencies (FontAwesome and Bootstrap)

I have received multiple requests to disable Bootstrap and FontAwesome. Foremost, doing this would break my template and interfere with my written and video guides on Joomla template creation. The point of this template is to build off it and learn how it works. So you can do this easily yourself if you really want. But there is a reason why I’m including it by default.

Virtually every layout Joomla uses requires Bootstrap’s grid or other features to function. If you do not include Bootstrap, you will have to override every single layout you use in the front end with custom HTML/Css. Without Bootstrap, columns will not work, responsive mobile-friendly behaviors may be broken, and features that require Bootstrap’s JavaScript won’t work. So things like accordions and dropdowns might look odd.

If you disable FontAwesome, all the system icons shown on the front end will not display. This includes things like the usename icon in the login form and various other important buttons.

Finally, many of Joomla’s third party extensions are built with the expectation that the template supports Bootstrap and FontAwesome. You will have to manually override every single layout of every third-party component you use.

In short, it’s much easier for you to just learn how to customize Bootstrap with SASS, or add your own custom CSS overrides.

How You Can Disable

Disabling Bootstrap and FontAwesome is very simple. There are several ways you could do it.

Removing Bootstrap’s CSS

To remove Bootstrap’s CSS, simply replace “template.min.css” with your own custom CSS file under media/templates/site/j4starter/css folder.

Alternatively, you can modify joomla.asset.json to use a different uri for “template.j4starter.mainstyles”

Removing Bootstrap’s Javascript: The lines that require Bootstrap’s Javascript are found in the template’s index.php file under templates/j4starter. Specifically, you want to remove the part around line 50.

HTMLHelper::_('bootstrap.collapse');
//dropdown needed for 2nd level menu items
HTMLHelper::_('bootstrap.dropdown');Code language: PHP (php)

The HTMLHelper function loads bootstrap’s dropdown and collapse functionality.

Removing FontAwesome

FontAwesome is included via a dependency in the joomla.asset.json file under your templates/j4starter folder. Simply delete the dependency under template.j4starter.mainstyles

{
  "name": "template.j4starter.mainstyles",
  "description": "The default css style to use.",
  "type": "style",
  "uri": "template.min.css",
  "dependencies": [
    "fontawesome"
  ]
},Code language: JavaScript (javascript)

Turns into…

{
  "name": "template.j4starter.mainstyles",
  "description": "The default css style to use.",
  "type": "style",
  "uri": "template.min.css"
},Code language: JavaScript (javascript)

Other Option: Don’t Use WebAssetManager

If you don’t want to use any of the styles or Javascript included with the template, you can also choose to not use WebAssetManager entirely. WebAssetManager is Joomla’s system for loading css and javascript. 

To stop using it, go to index.php and delete these lines in the head section.

<jdoc:include type="metas" />
<jdoc:include type="styles" />
<jdoc:include type="scripts" />Code language: HTML, XML (xml)

The jdoc include functions load the styles and scripts from joomla.asset.json. So deleting this removes them all. You can also delete these lines in the php above it.

HTMLHelper::_('bootstrap.collapse');
//dropdown needed for 2nd level menu items
HTMLHelper::_('bootstrap.dropdown');Code language: PHP (php)

Then, you can include your own custom CSS and JavaScript the way you would with any standard HTML document, by linking to them in the head.

<head>
    <link rel="stylesheet" href="/path_to_your_css_file.css" type="text/css" />
    <script src="/path_to_your_javascript_file.js"></script>
</head>Code language: HTML, XML (xml)

So, now you know how to remove FontAwesome and Bootstrap. Though again, I don’t recommend it. If you plan on using Joomla without these, you’re just creating a lot of extra work for yourself. If you don’t use any of Joomla’s core functionality or third-party extensions, which depend on this, then your project might not need Joomla to begin with!

Changelog

• Version 1.40 – Oct 26, 2023 – Updated for Joomla 5 and renamed JoomStarter
• Version 1.10 – Feb 21 2022 – Updated to support child templates
• Version 1.01 – Feb 6 2022 – Updated to fix an issue with viewports
• Version 1.0 – Nov 2021 – First version of the template