Menu
Kevin's Guides

Joomla 4/5 Blank Template - JoomStarter

Joomla 4/5 Blank Template - JoomStarter
1 Comment

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


Packaged File Structure


joomstarter/
|-- html/
|   `-- mod_menu/
|       |-- collapse-default.php
|       |-- default.php
|       |-- default_component.php
|       |-- default_heading.php
|       |-- default_separator.php
|       `-- default_url.php
|-- language/
|   `-- en-GB/
|       |-- tpl_joomstarter.ini
|       `-- tpl_joomstarter.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
        
New: Skeletal Template

Due to request, I have created a significantly simpler template than JoomStarter. If you're just looking for the absolute, most barebones template to start with, this is it. However, it's not right for every use case. Please review if it's a right fit for you first.


Details & Warnings

It does not include additional dependencies or files typically used by Joomla and Joomla extensions, such as FontAwesome and Bootstrap. It contains just 4 files - the index.php layout file, templateDetails.xml file, a css file to put your css in, and a JavaScript file to add JS. It's all contained in a single folder and can be used that way.

If you decide to go this route, the template itself is simpler. However, there are many reasons I would recommend going with JoomStarter instead. Namely, JoomStarter follows standard Joomla conventions and uses the dependencies required by most Joomla extensions. The Skeletal template does not.

In short, for very basic websites with few third-party extensions, this template may be adequate. It's a good starting point if you're looking for the absolute, most basic thing possible.

If you are aiming to develop professional and more advanced templates I would highly suggest starting with JoomStarter instead, and following the full guide. In the long run, unless you're making a very basic static website, this skeletal template may actually require MORE work despite the simpler initial design.

With that said, feel free to check out JoomSkeletal if you'd like.

JoomSkeletal Template Download


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');

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"
      ]
    },

Turns into...


    {
      "name": "template.j4starter.mainstyles",
      "description": "The default css style to use.",
      "type": "style",
      "uri": "template.min.css"
    },

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" />

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');

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>

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
Write comments...
You are a guest ( Sign Up ? )
or post as a guest
Loading comment... The comment will be refreshed after 00:00.
  • This commment is unpublished.
    MrMarcie · 6 months ago
    Thanks that I found this 'blank' template. The basics I worked with for J3 are not working anymore. So now I'm happy I found a new starter template to build templates for my clients. I'm not good in this coding but more a frontend developer so this one helps me a lot. Awesome!

Related Guides

Changing The Default Cassiopeia Favicon
How to change the default favicon in the Joomla 4 Cassiopeia template.
Custom Bootstrap Styles/Variables in your Joomla Template
How to customize Bootstrap to better suit your template using Sass.
Joomla Template Override Locations
How to override default component and module layouts/templates in Joomla using template overrides.
Chapter 1: What is Joomla?
In this series introduction, you will learn what Joomla is, what it's for, and some of its key aspects.
Chapter 2: Set Up Your Joomla Test Environment
This chapter details how to get Joomla 4 up and running on a local test server (your computer with XAMPP).
Chapter 3: Administrator Essentials
Learn some administrator essentials in Joomla 4, including Global Configuration and about the different types of extensions.
Main Menu
Kevin's Guides
Full size image will appear here.