- Details
- Category: Guides
- Hits: 3251
This tutorial provides a beginner-friendly introduction to creating Joomla! templates. We'll walk through the essential files and code required to build a basic template. The examples are designed to be easy to use, so you can copy and paste them with minimal adjustments.
Building a Joomla template from scratch gives you full control over your website's design, functionality, and user experience. It allows you to move beyond pre-made templates and create a site that perfectly fits your unique needs.
Let’s get started building your Joomla Template!
Project Requirements
To follow along building your Joomla template you will need to have a good understanding of the web design fundamentals. It's nothing complicated, but some prior knowledge will come in handy. You will need:
- Basic Knowledge of HTML, CSS, and PHP: Familiarity with these languages will make the process much easier.
- A Text Editor: You can use an app like Visual Studio Code, Sublime Text, or Notepad++ to write code. I will be using Visual Code Studio.
- FTP/File uploader: If you are building on the web, you may need an FTP client like FileZilla. However, I will be working with cPanel's file manager.
- Joomla Installed: Set up Joomla on a local server or a live site to test your template as you build it. You don't need a domain but, if needed, you can see this list of premium domains.
With that out of the way, let's move forward.
Create the template files
The first step is to set up the folder structure for your template, which is quick and easy. Start by navigating to the templates folder within your Joomla installation's file structure. This folder contains all the templates for your site. Create a new folder here and give it a name. For this tutorial, we’ll create a folder called "my-custom-template
" to house our template files.
Once you have created the folder, it's time to place the most important theme files. The most important files and directories are:
- index.php: The main template file that controls the layout.
- templateDetails.xml: The manifest file that Joomla uses to install and recognize your template.
- css/ folder: Contains all your CSS files.
- js/ folder: Contains all your JavaScript files
- images/ folder: For template images (like logos or background images).
- error.php: The file that displays custom error messages.
So your directory should look something like this:
my-custom-template/
│
├── css/
│ └── template.css
├── js/
│ └── script.js
├── images/
├── index.php
├── templateDetails.xml
├── error.php
Now let's start populating our files and directories. We'll start with the templateDetails.xml file.
Step 1: templateDetails.xml file
To create a template in Joomla, the first step is creating the manifest file. The manifest file is called `templateDetails.xml`. This file is essential because it contains all the information about your template, such as its name, author, version, and other important details.
You don't need to be an expert in XML (Extended Markup Language) to understand or create this file. The key tags in the manifest file include:
- <name>:
The name of your template.
- <creationDate>
: The date the template was created.
- <author>
: The name of the template's creator (you).
- <authorEmail>
: Your email address as the author.
- <authorUrl>
: The URL of your website.
- <copyright>
: The copyright owner of the template.
- <license>
: Information about the template's license.
- <version>
: The current version of your template.
- <description>
: A brief description of your template.
- <files>
: A list of all the files included in the template for installation.
- <positions>
: Defines the module positions in your template.
Without it, your template won't be seen by Joomla! This is how it should look:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 2.5//DTD template 1.0//EN" "https://www.joomla.org/xml/dtd/2.5/template-install.dtd">
<extension version="3.1" type="template" client="site">
<name>My Custom Template</name>
<version>1.0</version>
<creationDate>31.12.2024</creationDate>
<author>Joomla Template Maker</author>
<description>Joomla Template Maker</description>
<files>
<filename>index.php</filename>
<filename>templateDetails.xml</filename>
<filename>template_preview.png</filename>
<filename>template_thumbnail.png</filename>
<filename>favicon.ico</filename>
<folder>css</folder>
</files>
<positions>
<position>menu</position>
<position>aside</position>
<position>footer</position>
</positions>
</extension>
Step 2: Create a simple index.php file
The index.php
file is the backbone of every page that Joomla generates. The template works by incorporating Joomla code into specific areas, such as module positions and the main component section. Anything you add directly to the template will appear on every page.
Below is a simple, ready-to-use code structure that you can copy and paste into your own design.
<?php defined( '_JEXEC' ) or die( 'Restricted access' );?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" >
<head>
<jdoc:include type="head" />
<link rel="stylesheet" href="/<?php echo $this->baseurl ?>/templates/system/css/system.css" type="text/css" />
<link rel="stylesheet" href="/<?php echo $this->baseurl ?>/templates/system/css/general.css" type="text/css" />
<link rel="stylesheet" href="/<?php echo $this->baseurl ?>/templates/<?php echo $this->template; ?>/css/template.css" type="text/css"
/>
<link rel="stylesheet" href="/<?php echo $this->baseurl ?>/templates/<?php echo $this->template;?>/css/styles.css" type="text/css" />
</head>
<body>
<img src="/<?php echo $this->baseurl; ?>/templates/<?php echo $this->template; ?>/images/myimage.png" alt="Custom image" class="customImage" />
<jdoc:include type="modules" name="menu" />
<jdoc:include type="component" />
<jdoc:include type="modules" name="bottom" />
</body>
</html>
Without going into much detail, here is a brief explanation of each section.
Start
The first line protects your code from unauthorized access and potential misuse.
The second line is the Document Type Declaration (DOCTYPE), which informs the browser and search engines about the version of HTML being used. In this case, it’s HTML5.
Head
The first line ensures Joomla generates the correct header information, including the page title, meta tags, and system JavaScript. The rest of the code creates links to two system stylesheets and your own stylesheet (assuming it’s named template.css
and located in the css
folder of your template directory).
Body
The first line of code:
<img src="/<?php echo $this->baseurl; ?>/templates/<?php echo $this->template; ?>/images/myimage.png" alt="Custom image" class="customImage" />
Adds a custom image to your template files. The image is uploaded into the images
directory. Don't forget to resize your images before uploading them to your site to ensure a better user experience.
The rest of the lines are jdoc statements. jdoc statements tell Joomla to include output from certain parts of the Joomla system.
Above, the line which says name="menu"
adds a module position called menu and allows Joomla to place modules into this section of the template. The type="component"
line contains all articles and main content.
Note: You can add your own module lines anywhere you want in the body, but you have to add a corresponding line to the templateDetails.xml
file.
Step 3: Style your template
The next step in creating a Joomla template is to design it using CSS. You can define the look and feel of your website by adding styles to the template.css
file in your template directory. Here is a very basic example of could be included in the CSS file.
body {
font-family: Lato, sans-serif;
color: #000;
background-color: #fff;
}
header {
background-color: #f2eeed;
color: #f6ea97;
padding: 15px;
text-align: center;
}
footer {
background-color: #f2eeed;
color: #f6ea97;
text-align: center;
padding: 15px;
}
There is no limit to your creativity. You can add as many styles as needed and also make your layout responsive using media queries.
Installing your template
Once the template files are ready, it's time to ZIP archive them (use the .zip format). You can then upload your template files to the website.
In the admin dashboard, visit System > Extensions and upload your ZIP file.
Then System > Site Template Styles to activate your template.
Testing and Improving
At this point, your theme will not look like much, but that's okay! It's up to you to build upon this guide and create a truly exceptional template.
After installing your template, test it thoroughly to make sure it’s responsive, loads quickly, and works well in different browsers. You can also turn on Joomla’s debugging mode to catch any errors.
Useful Testing Tools:
- Chrome Developer Tools: To inspect elements and fix CSS issues.
- PageSpeed Insights: To check performance, accessibility, and SEO.
If you built your template on your local computer and are ready to go live, check out our guide on moving Joomla from localhost to a live server.
Congrats on creating your Joomla Template!