Building A Custom Joomla 5 Template

My Super User
Joomla! Tips
Views: 245

The Bad News: Building a template from scratch is hard. 

The Good News: You don't have to. 

Now that we got that out of the way, let's discuss what it takes to create your own template and why we should give far more praise to all the developers who have put together the 'Cassiopeia' template that comes packed with every new Joomla 5 install.

There are a lot of moving parts that go into building your own template and if they aren't "clicking on all cylinders", it could cause you lots of problems.  Instead of starting from scratch, we copied the most current version of 'Cassiopeia' and renamed it 'My Template'. Why not just use the current 'Cassiopeia' instead of going through the hassle of copying and updating all the files and references? 

  • Reason #1 : The deeper you get, the more changes you will make, some of those changes will end the way you wish them to. Keeping the original 'Cassiopeia' template "pure" gives you a quick reference to see what differences you made between a particular item that may not be working properly for you. It's your safety net (which you will need when you get a little too overconfident).
  • Reason #2 : The purpose of this site is to show how to build your own template that you can grow and evolve with your current and future website projects. With every new project you work on, you will discover new things in your template building that will allow you to add new features and benefits to your "upgraded" templates. When you use the same framework and backend structure with all of new projects, it makes it easier for you to manage and share these new features with your previous projects that used an older version of your template. 
  • Reason #3 : Knowing all the pieces that make up a template (especially when you have to copy/rename/update references) will bring you more awareness and make you a better developer. 

Step 1 - Copying The Template Files

The following list of items are the files and folders you need to copy for your first template. The next step will focus on what to change in those files in order to make sure you have no issues when you install it for the first time. For this first time, it may be easiest to simply copy these items into a separate folder on your desktop until we are ready to install. We will be using the same naming structure we used for the template used on this site.

  1. We will first copy the template folder 'cassiopeia' from the 'templates' directory found in the root of your Joomla install and rename the folder 'mytemplate'
  2. Inside 'mytemplate' create a new folder and title it 'language' and another sub-folder titled 'en-GB' (or whatever your website language is)
  3. Copy 'tpl_cassiopeia.ini' and 'tpl_cassiopeia.sys.ini' from the 'language/en-GB' directory found in the root of your Joomla install and paste inside your new 'language/en-GB' folder you just created in Step 2.
  4. Copy the 'cassiopeia' folder from 'media/templates/site' directory and paste into your 'mytemplate' folder created in Step 1.
  5. Rename the 'cassiopeia' folder copied in Step 4 to 'media'

So you should now have a folder structure that looks like this:

  • mytemplate
    • html
      • layouts
      • mod_custom
      • mod_menu
      • tinymce
    • language
      • en-GB
        • tpl_mytemplate.ini
        • tpl_mytemplate.sys.ini
    • media
      • css
      • images
      • js
      • scss
    • component.php
    • error.php
    • index.php
    • joomla.asset.json
    • offline.php
    • templateDetails.xml

Step 2 - Updating Your Template Files

Once your new 'mytemplate' folder looks identical to the structure in the previous step, we will now have to go into some of the files to make some edits so everything will end up pointing to the new template instead of the old one. The following template files will need to be updated before you zip the 'mytemplate' folder and install on your Joomla site. All file/folder locations are referencing your 'mytemplate' folder as the root:

  • Language Files (found in the 'language/en-GB'):
    • tpl_mytemplate.ini - do a "find and replace" for: TPL_CASSIOPEIA and replace with TPL_MYTEMPLATE
    • tpl_mytemplate.ini - replace CASSIOPEIA="Cassiopeia Site template" with MYTEMPLATE="My Custom Site Template"
    • tpl_mytemplate.ini - change the text inside the quotes to match your new template description for TPL_MYTEMPLATE_XML_DESCRIPTION=""
    • tpl_mytemplate.sys.ini - do a "find and replace" for: TPL_CASSIOPEIA and replace with TPL_MYTEMPLATE
    • tpl_mytemplate.sys.ini - replace CASSIOPEIA="Cassiopeia Site template" with MYTEMPLATE="My Custom Site Template"
    • tpl_mytemplate.sys.ini - change the text inside the quotes to match your new template description for TPL_MYTEMPLATE_XML_DESCRIPTION=""
  • component.php, error.php, index.php, offline.php, joomla.asset.json - do a "find and replace" for: cassiopeia and replace with mytemplate
  • templateDetails.xml:
    • Change <name>cassiopeia</name> to <name>mytemplate</name>
    • Change <media destination="templates/site/cassiopeia" folder="media"></br>to <media destination="templates/site/mytemplate" folder="media">
    • Replace tpl_cassiopeia.ini with tpl.mytemplate.ini
    • Replace tpl_cassiopeia.sys.ini with tpl.mytemplate.sys.ini
    • Do a "find and replace" for: TPL_CASSIOPEIA_ and replace with TPL_MYTEMPLATE_
    • Do a "find and replace" for: site/cassiopeia/ and replace with site/mytemplate/

Congratulations! If you have made it this far, you are about to embark on a journey that will give you the tools to mold your future Joomla projects in ways you have only dreamed about. As a reward for your efforts, you can download the new template to install on your Joomla 5 site here: tpl_mytemplate

Related Articles