Joomla Template Basics — Cassiopeia, Template Manager and Structure

In this tutorial, you'll learn how Joomla templates control your site's appearance — from the Cassiopeia default template and the Template Manager to the template folder structure and templateDetails.xml configuration file.

What You'll Learn

• What templates are and how they control site layout, styling, and module positions
• The default templates: Cassiopeia for frontend and Atum for admin
• How to use the Template Manager (Extensions > Templates > Styles)
• How to edit template styles: style name, default status, assignment to pages, advanced options
• The template folder structure inside templates/cassiopeia/
• What templateDetails.xml contains and how to read it
• Template inheritance in Joomla 4+ vs Joomla 3
• How template styles work — duplicating templates for variations
• Cassiopeia features: Bootstrap 5, no jQuery, accessible, dark mode
• The built-in template editor for editing HTML and CSS online

Why It Matters

Your template is the first thing visitors notice about your site. A well-chosen and properly configured template establishes brand identity, ensures accessibility, and controls how content is presented across devices. Without understanding templates, you are stuck with the default look and cannot customize your site. Every Joomla site Builder needs to master templates because they determine the user experience more than any other single factor.

Real-World Use

A small business launches a Joomla site for their bakery. They use the Cassiopeia template because it is accessible, mobile-friendly, and loads fast without jQuery. They duplicate the template style to create a second variation with a different header color for their seasonal promotions page. The menu module automatically appears in the correct position because Cassiopeia defines all the module positions in its templateDetails.xml.

Learning Path

flowchart LR
  A["Modules & Positions"] --> B["Template Basics
You are here"]:::current
  B --> C["Template Styles"]
  C --> D["Template Overrides"]
  D --> E["Child Templates"]
  E --> F["CSS & User.css"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px

What Is a Template in Joomla?

A template is a set of files that controls how your Joomla site looks. It is the skin that wraps around your content. The template provides the HTML structure, the CSS styling, the JavaScript behavior, and the positions where modules can appear.

Think of a template like the frame and decoration of a house. The content — articles, categories, contacts — is the furniture inside. You can rearrange the furniture (content) without changing the house structure, but if you want different room sizes (layout), you need a different blueprint (template).

Templates vs. Template Styles

A template is the underlying code — the collection of PHP, CSS, and XML files. A template style is a saved configuration of that template's options. You can have multiple styles for the same template, each with different colors, fonts, or logo settings.

For example, Cassiopeia is the template. You can create "Cassiopeia — Default" and "Cassiopeia — Blue Version" as two different styles. Both use the same underlying template files but display different colors.

Default Templates

Joomla ships with two default templates:

Cassiopeia

Cassiopeia is the default frontend template introduced in Joomla 4. It is built with Bootstrap 5 and has no jQuery dependency. This makes it faster and more secure than older templates. Cassiopeia is fully accessible (WCAG 2.1 AA compliant), supports dark mode via the prefers-color-scheme media query, and includes built-in blog layouts.

Atum

Atum is the default administrator template. It is also built with Bootstrap 5 and provides a clean, modern interface for managing your site. Atum supports dark mode and is fully responsive so you can manage your site from mobile devices.

Template Manager

You access the Template Manager from Extensions > Templates. There are two views:

Templates View

Extensions > Templates > Templates shows the installed templates. You can see Cassiopeia, Atum, and any other templates you have installed. Clicking a template name takes you to the template editor where you can view and edit the template files.

Styles View

Extensions > Templates > Styles shows the template styles. This is where you configure how a template looks. Each style has its own settings for colors, fonts, logo, and layout. You can have multiple styles for the same template.

# Path to the Template Manager in the admin menu
# Extensions > Templates > Templates or Styles
# Both views are accessible from the same parent menu

Editing a Template Style

When you click a style name in the Styles view, you see:

1. Style Name: A descriptive name for this style configuration
2. Default: Whether this is the default style for the site
3. Assignment: Which menu items this style applies to
4. Advanced Options: Template-specific settings like colors, fonts, layout

Let's walk through the Cassiopeia style editor:

Style Name and Default Status

The style name helps you identify which style is which. The default style (marked with a star) is applied to all pages that do not have a specific style assignment.

Assignment to Pages

You can assign a style to specific menu items. For example:

• Assign your default style to all pages
• Create a second style with a different header for your blog section
• Create a third style with a dark color scheme for a special landing page

The assignment tab shows a tree of menu items. You check the ones that should use this style.

Advanced Options

The options available depend on the template. Cassiopeia offers:

• Brand: Logo upload, site title, tagline
• Color: Link color, text color, background colors
• Font: Headings font, body font
• Layout: Template width, sidebar positions
• Header: Style, height
• Menu: Type, animation
• Background: Color, image

Template Folder Structure

Every template lives in the templates/ folder. Let's look at Cassiopeia's structure:

templates/cassiopeia/
├── error.php
├── index.php
├── component.php
├── templateDetails.xml
├── css/
│   ├── template.css
│   └── user.css
├── js/
│   ├── template.js
│   └── mod_menu.js
├── images/
│   ├── joomla.png
│   └── template.svg
└── html/
    └── com_content/
        └── article/
            └── default.php

Key Files

How index.php Works

The index.php file is the heart of the template. It builds the HTML page structure and includes module positions and component output.

<!DOCTYPE html>
<html lang="<?php echo $this->language; ?>" dir="<?php echo $this->direction; ?>">
<head>
  <jdoc:include type="head" />
  <link href="<?php echo $this->baseurl; ?>/templates/<?php echo $this->template; ?>/css/template.css" rel="stylesheet">
</head>
<body>
  <header>
    <jdoc:include type="modules" name="menu" />
  </header>
  <main>
    <jdoc:include type="message" />
    <jdoc:include type="component" />
  </main>
  <aside>
    <jdoc:include type="modules" name="sidebar-right" />
  </aside>
  <footer>
    <jdoc:include type="modules" name="footer" />
  </footer>
</body>
</html>

The <jdoc:include> tags are Joomla's way of including content:

• type="head" — includes <head> elements: meta tags, stylesheets, scripts
• type="component" — includes the main component output (the article, contact, etc.)
• type="modules" — includes modules assigned to a specific position
• type="message" — includes system messages

templateDetails.xml

This XML file tells Joomla everything it needs to know about the template.

<?xml version="1.0" encoding="utf-8"?>
<extension version="4.0" type="template" client="site">
  <name>cassiopeia</name>
  <version>1.0</version>
  <creationDate>2023-12-15</creationDate>
  <author>Joomla Project</author>
  <description>Cassiopeia is the default frontend template for Joomla 4 and 5.</description>

  <positions>
    <position>menu</position>
    <position>sidebar-right</position>
    <position>sidebar-left</position>
    <position>footer</position>
    <position>topbar</position>
    <position>bottom</position>
    <position>breadcrumbs</position>
  </positions>

  <files>
    <filename>index.php</filename>
    <filename>error.php</filename>
    <filename>component.php</filename>
    <folder>css</folder>
    <folder>js</folder>
    <folder>images</folder>
  </files>

  <languages>
    <language tag="en-GB">language/en-GB/tpl_cassiopeia.ini</language>
  </languages>
</extension>

Key elements:

• <extension> — the root element, with type="template" and client="site" for frontend
• <name> — the internal template name, also used as the folder name
• <positions> — defines all module positions the template supports
• <files> — lists every file and folder in the template
• <languages> — language files for template strings

Module Positions in Cassiopeia

The positions defined in templateDetails.xml determine where you can place modules. Cassiopeia includes:

Template Inheritance

In Joomla 3, template inheritance used the Isis and Hathor templates as base themes. You would subclass them using $this->subtemplate.

In Joomla 4 and 5, template inheritance works differently. Instead of subclassing, you create a child template that inherits from a parent. The child template specifies a parent in its templateDetails.xml.

Template inheritance is less common in Joomla 4+ because Cassiopeia is designed to be customized through the style customizer and user.css. You only need a child template when you want to modify the core template structure.

<!-- templateDetails.xml for a child template inheriting Cassiopeia -->
<?xml version="1.0" encoding="utf-8"?>
<extension version="4.0" type="template" client="site">
  <name>my_cassiopeia_child</name>
  <inherit>
    <template>cassiopeia</template>
  </inherit>
  <description>My custom child template based on Cassiopeia</description>
</extension>

Template Styles

You can create multiple styles for the same template. Each style is a saved set of configuration options. This lets you:

• Create a light and dark version of the same template
• Use different logos for different sections of the site
• Apply different color schemes for different client sites

To create a new style:

1. Go to Extensions > Templates > Styles
2. Click the Cassiopeia style
3. Click the Duplicate button in the toolbar
4. Rename the new style
5. Change the options (colors, logo, etc.)
6. Assign it to specific menu items

# Steps to duplicate a template style
# 1. Extensions > Templates > Styles
# 2. Click checkbox next to Cassiopeia - Default
# 3. Click Duplicate in the toolbar
# 4. Click the new style to edit it
# 5. Change name and settings
# 6. Assign to menu items
# 7. Save and Close

Cassiopeia Features

Bootstrap 5

Cassiopeia uses Bootstrap 5 for its grid system, components, and utilities. This means:

• Responsive grid classes (col-md-6, col-lg-4, etc.)
• Bootstrap components (navbars, cards, modals, etc.)
• Utility classes (text-center, mt-3, d-flex, etc.)
• No legacy jQuery dependency

No jQuery Dependency

Older Joomla templates relied on jQuery for JavaScript interactions. Cassiopeia uses vanilla JavaScript and Bootstrap 5's native JS. This reduces page weight and eliminates jQuery-related conflicts.

Accessibility

Cassiopeia meets WCAG 2.1 AA standards. This means:

• Proper heading hierarchy
• ARIA landmarks and roles
• Keyboard navigation support
• Focus indicators
• Sufficient color contrast

Dark Mode

Cassiopeia supports dark mode natively. If the user's operating system is set to dark mode, Cassiopeia automatically switches to a dark color scheme:

/* Cassiopeia's dark mode detection */
@media (prefers-color-scheme: dark) {
  :root {
    --cassiopeia-color-primary: #38bdf8;
    --cassiopeia-color-text: #e2e8f0;
    --cassiopeia-color-bg: #1e293b;
  }
}

Blog Layouts

Cassiopeia includes built-in layouts for blog pages:

• Leading article (full width)
• Multiple articles in a grid
• Article links (titles only)
• Category list layout

Built-in Template Editor

Joomla includes a file editor for templates:

1. Extensions > Templates > Templates
2. Click Cassiopeia
3. You see the template files in a tree view
4. Click any file to edit it in the browser
5. Click Save to apply changes

This is useful for quick edits but use it carefully. Errors in the template files can break the site. Always test changes on a staging site first.

The editor supports:

• Syntax highlighting
• File creation
• File deletion
• Folder creation

# Access the built-in template editor
# Extensions > Templates > Templates > Cassiopeia
# Files are listed in the sidebar
# Click to open in the editor
# Edit and click Save

Common Mistakes

1. Editing the template directly instead of creating overrides: Beginners edit the Cassiopeia index.php file directly. When Joomla updates Cassiopeia, those changes are lost. Always use template overrides or a child template instead.

2. Not understanding template styles: Creating a new style is different from creating a new template. Beginners sometimes try to create a whole new template when they just need to duplicate and customize a style.

3. Forgetting About module position limitations: Module positions are defined in templateDetails.xml. If you try to assign a module to a position that doesn't exist in the current template, the module will not appear. Always check available positions.

4. Breaking the site with the template editor: The built-in template editor does not validate your code. A typo in index.php can make the entire site inaccessible. Always have a backup before editing template files.

5. Using too many templates: Installing multiple templates adds overhead. Each template has its own files, language strings, and option sets. Stick to one or two templates and customize them through styles and overrides.

Practice Questions

1. What is the difference between a template and a template style? Answer: A template is the underlying code (PHP, CSS, XML files). A template style is a saved configuration of that template's options. The same template can have multiple styles with different colors, fonts, and assignments.

2. What file defines the module positions available in a template? Answer: The templateDetails.xml file defines all module positions using the <positions> element. The positions listed there are the only ones you can assign modules to in that template.

3. Why does Cassiopeia not use jQuery? Answer: Cassiopeia uses Bootstrap 5 and vanilla JavaScript instead of jQuery. This reduces page weight, improves performance, and eliminates jQuery-related security vulnerabilities and compatibility issues.

4. Challenge: Create a custom template style for Cassiopeia that applies a different color scheme to your blog section. Duplicate the default Cassiopeia style, rename it to "Blog Style", change the link color to a shade of green, assign it to all blog menu items, and verify that blog pages show the new color while other pages keep the default.

FAQ

Mini Project

Your task: Explore and document the Cassiopeia template structure.

1. Go to Extensions > Templates > Templates and click Cassiopeia.
2. List all the files and folders in the template.
3. Open index.php and identify the module positions used.
4. Open templateDetails.xml and note the module positions defined there.
5. Create a new template style by duplicating Cassiopeia's default style.
6. Rename your style to "My Practice Style".
7. Change the link color to a custom value.
8. Assign the style to one menu item.
9. Visit the frontend and verify the color change appears only on that page.
10. Document which module positions appear on the page and where they are located.

This exercise gives you hands-on experience with template structure, styles, and assignments — skills you will use on every Joomla project.

What's Next

Now that you understand template basics, you are ready to customize the look of your site:

Continue to Lesson 16: Template Styles — Learn how to use the Cassiopeia style customizer to change colors, fonts, layout, and create multiple style variations.

Related lessons:

• Joomla Modules and Positions — Learn what module positions are and how to assign modules
• Joomla Template Overrides — Customize component layouts without modifying core files