Customize your Cassiopeia Template

Location of the Template in Joomla

In the Joomla 4 backend you can find Cassiopeia in the menu item System.

There is a box with the headline "Templates". Click on Site Template Styles to get a list of all current template styles.

Click on the Cassiopeia Default title/link to display the settings for this style.

Template Style Settings

In the advanced tab of the Template Style you can setup following:

1) Logo / Brand

Brand: Enable disable the display of your brand completely
Logo: Upload a Logo for your template
Title: Display alternatively a title instead of the logo image
Tagline: Display a tagline below the logo or title

2) Fonts

You can change the font of your template in the Fonts Scheme dropdown. There is one predefined local font "Roboto" which is also used by the backend template. It supports most languages and is good to read. It's hosted locally because loading fonts from external sources might be against privacy regulations in some countries. On the other side loading fonts from a local folder might have a performance impact on your site. You can also select to load Fira Sans or Roboto + Noto Sans from the web. How to add own fonts will be covered later.

3) Colors

There are two Color presets in the Cassiopeia template
Select Standard for the purple theme, Select Alternative for a wine-red theme. Adding own colors will be covered again later on.

4) Layout

Layout: Chose between static and fluid to have a "boxed" or a full-page layout
Sticky Header: Chose Yes to have the header position always visible on scrolling.

The Sticky header only applies to Screens larger than 992px

5) Other features

Back-to-top-link: Select yes to have a to-top-link displayed on your webseite at the bottom right corner.

Module Positions and Settings

Before we look into how to change colors and fonts on the website let's see what module positions we have and what to to to have a dropdown navigation.

How to find the module positions

You can preview your module positions by clicking on the previewlink in the template style list. If there is a crossed eye, you have to enable module preview in the template options (Click on the options button on the top right).

If you click on the preview link you get a preview of your front page with some of the available module positions.

Here, I prepared for you a complete overview of the current Cassiopeia module positions.

Set up the modules

Now that you know what module positions you have, lets do some two basic settings almost everyone would want to have for the Cassiopeia Template.

Change the Menu Module Settings

In your Joomla backend navigate to Content » Site Modules and you find there the Breadcrumbs, the Main Menu and the Login Form. To change the settings for the menu you click on the Title/Link Main Menu.

Assign the module position

First thing to do, is to assign your module to the menu position.

That will show your menu at the top and in horizontal position.

Change the Menu Layout

But when you hover a parent item, nothing happens actually and you might want to have a dropdown menu here. To achieve this you change some more module settings:

In the advanced tab of your menu module you can select in the Layout field Collapsible Dropdown or Dropdown from the Cassiopeia Template

The difference between those options is visible in mobile view where a burger icon is shown when you select collapsible Dropdown and the menu items are stacked when you select just the regular dropdown.

Adding a Site header

If you want to have a fancy site header like displayed in the Cassiopeia Demo pages you create a new module of the type custom.

Module Settings

Hide the title of your module
Put the module on position banner
Be sure its published
Type in some text you want to display in the editor window
And check in the menu assignments where you want to publish it
In the Options tab select a background image
In the advanced tab select a banner as layout

Customizing your template

That were the basics. To customize the Cassiopeia template more to your style and needs you need to add some CSS Styling.

Adding the user.css file

If you want to change the colors or something else of Cassiopeia you need to add an user.css file to your template folder. You can reach your template if you click on the template name in the template styles (template column on the right).

You can also reach your template folder by navigating to System » Site Templates

Create user.css file (if not already present)

Click on the New File Button at the top
Name the file user in the File Name field (see image below)
select the File Type css
Click on the folder css on the left – be absolutely sure that the folder is really marked!
Click on "Create"
Check that the user.css file is really inside the css folder (it's a common mistake to do this wrong)

You should now have a user.css file in your css folder. Joomla automatically recognizes that you have done this and reads your CSS instructions out of it.

Some CSS Basics

Before I continue we need to do a small CSS cardio training. Sorry, but that's really important for you to know at least the very very basics of css to be able to survive in the template world.

I promise I keep it as simple and short as possible.

CSS - What is that actually?

In short, you use CSS (Cascading Style Sheets) to define how something should look.

There are many commands that help you to design your content and your template.

A CSS command always looks like this:

CSS can be applied in several ways.

Inline Styles

If you color a text directly in your Joomla WYSIWYG editor and switch to HTML mode, you will notice that your colored fonts look like this.

Here the CSS command is inserted as a so-called inline style in an attribute. But you should do this only in very rare exceptions. It is better to write CSS in a separate file. And this is where our user.css file comes into play.

How to address a specific element on the web page?

html elements

There are html elements, that is for example a heading, a paragraph or a list. Elements are addressed by directly inserting the element name into the CSS file. For example a h1 heading.

IDs

There are html elements that have an ID. In the html code it would look like this.

For someone who writes HTML, it is important to know that an ID may only appear once on the entire page. So for our example, there must not be any other element with the id="main".

You control the style of an element with an ID in CSS by writing a hash in front of the ID.

Classes

There are html elements that have one or more classes. In the code it would look like this:

You control a class in CSS by writing a dot in front of the class.

You can also concatenate classes together by naming them both

For example:

Combine elements, IDs and classes

Example

<p id="special" class="myclass">
  <h1>
    Headline
  </h1>
</p>

You can combine CSS statements. In the code example above we have an HTML element for a paragraph (p) with the ID special and the class myclass. In it there is a heading with html element h1 - You can address the paragraph in different ways.

For example:

p {
color: #ff0000;
}

This way you will color all paragraphs on the whole web page red.
But you might not want to do that?

Then you could write:

.myclass {
color: #ff0000;
}

This will color all elements with the class myclass on the web page red.
But maybe you don't want that?

p.myclass {
color: #ff0000;
}

By naming the html element and the class you color all paragraphs with the class myclass red.

What to do with our h1 Headline inside the paragraph?

Example:

p.myclass h1 {
color: #ff0000;
}

By writing an element a class or an ID with space after other Statements, you address the element inside the other ones.

With this statement, you will color all h1 headings that are inside a paragraph with the class main to red.

Pseudo Elements

If you want to change an element while hovering over it, you can do that with the :hover command.

.btn-primary {
  background: rgba(119,9,121,1);
}

.btn-primary:hover {
  background: rgba(0,212,255,1);
}

There are of course more pseudo Elements, but that's it for now with some basics of css. I think it's important to know at least this and then grow your knowledge by the specific usecases you have.

Popular CSS instructions and helpful links.

Background color	background: rgb(2,0,36);
Background gradient	background: linear-gradient(90deg, rgba(2,0,36,1) 0%, rgba(119,9,121,1) 35%, rgba(0,212,255,1) 100%);	https://cssgradient.io/
Inside distance	padding: 20px	https://www.w3schools.com/css/css_padding.asp
Inside distance top, right, bottom, left	padding: 20px 10px 20px 0px;
Inside distance to the right	padding-right: 20px
Outer distance	margin: 20px;	https://www.w3schools.com/css/css_margin.asp
Outer distance top, right, bottom, left	margin: 20px 10px 20px 0px;
Outer distance to the right	margin-right: 20px
Font color	color: #ff0000;
Font size	font-size:18px;
Font type	font-family: "Times New Roman", sans-serif;	https://www.w3schools.com/css/css_font.asp
font weight	font-weight: bold;
Box shadow	box-shadow: 12px 4px 18px 0px rgba(0,0,0,0.35); -webkit-box-shadow: 12px 4px 18px 0px rgba(0,0,0,0.35); -moz-box-shadow: 12px 4px 18px 0px rgba(0,0,0,0.35);	https://cssgenerator.org/box-shadow-css-generator.html
Text shadow	text-shadow: 2px 2px 8px rgba(150, 150, 150, 1);	https://css3gen.com/text-shadow/
border	border: 2px solid #ff0000;	https://www.w3schools.com/css/css_border.asp

Example user.css with comments for cassiopeia

/* Import font from Google - Go to fonts.google.com, select a font and look for the import command */

@import url('https://fonts.googleapis.com/css2?family=Georama:wght@100&display=swap');

/* Change some root colors and settings of the document */

:root {

    --cassiopeia-color-primary: #00ff00;
    --cassiopeia-color-link: #0000ff;
    --cassiopeia-color-hover: #ff0000;

    --cassiopeia-font-family-body: "Roboto", sans-serif;
    --cassiopeia-font-family-headings: "Roboto", sans-serif;
    --cassiopeia-font-weight-headings: 700;
    --cassiopeia-font-weight-normal: 400;
    
    --blue: #0d6efd;
    --indigo: #6610f2;
    --purple: #6f42c1;
    --pink: #d63384;
    --red: #dc3545;
    --orange: #fd7e14;
    --yellow: #ffc107;
    --green: #198754;
    --teal: #20c997;
    --cyan: #0dcaf0;
    --white: #fff;
    --gray: #6c757d;
    --gray-dark: #343a40;
    --gray-100: #f8f9fa;
    --gray-200: #e9ecef;
    --gray-300: #dee2e6;
    --gray-400: #ced4da;
    --gray-500: #adb5bd;
    --gray-600: #6c757d;
    --gray-700: #495057;
    --gray-800: #343a40;
    --gray-900: #212529;
    --primary: #0d6efd;
    --secondary: #6c757d;
    --success: #198754;
    --info: #0dcaf0;
    --warning: #ffc107;
    --danger: #dc3545;
    --light: #f8f9fa;
    --dark: #212529;
    --primary-rgb: 13, 110, 253;
    --secondary-rgb: 108, 117, 125;
    --success-rgb: 25, 135, 84;
    --info-rgb: 13, 202, 240;
    --warning-rgb: 255, 193, 7;
    --danger-rgb: 220, 53, 69;
    --light-rgb: 248, 249, 250;
    --dark-rgb: 33, 37, 41;
    --white-rgb: 255, 255, 255;
    --black-rgb: 0, 0, 0;
    --body-color-rgb: 33, 37, 41;
    --body-bg-rgb: 255, 255, 255;
    --font-sans-serif: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", "Liberation Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
    --font-monospace: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
    --gradient: linear-gradient(180deg, rgba(255, 255, 255, 0.15), rgba(255, 255, 255, 0));
    --body-font-family: var(--cassiopeia-font-family-body);
    --body-font-size: 2rem;
    --body-font-weight: 400;
    --body-line-height: 1.5;
    --body-color: #383838;
    --body-bg: #efefef;
}


/* Use the importeed font (See first lines of the document) on the page: On Google you can also find the CSS instruction for using the font. If you put this in the body element then the font will be used on the whole website. */

body {
    font-family: 'Georama', sans-serif;
}

/* The page header of Cassiopeia has the class "header" so you control it with .header */

.header {
    background: rgb(2, 0, 36);
    background: linear-gradient(90deg, rgba(2, 0, 36, 1) 0%, rgba(119, 9, 121, 1) 35%, rgba(0, 212, 255, 1) 100%);
}

/* Smaller banner */
.container-banner .banner-overlay {
    height: 40vh;
}


/* Color the dropdown menu in the menu with the class .metismenu.mod-menu .mm-collapse */

.metismenu.mod-menu .mm-collapse {
    background: #475BAF;
}

/* The links in the dropdown menu you have to adress them individually */

.metismenu.mod-menu .mm-collapse .metismenu-item a {
    color: #fff;
}

/* Modules have the class card, so you control them with .card - if you want to control only a specific module, you can give the module its own CSS class in the settings and then control it with that */

.card {
    box-shadow: 12px 4px 18px 0px rgba(0, 0, 0, 0.35);
    -webkit-box-shadow: 12px 4px 18px 0px rgba(0, 0, 0, 0.35);
    -moz-box-shadow: 12px 4px 18px 0px rgba(0, 0, 0, 0.35);
}

/* Modules are on different module positions in the Cassiopeia template then the modules get in addition to card also the position as class name, for example main-top - so if you want to change all modules to main top you take .main-top.card */

.main-top.card {
    background: #e1e9f5;
}


/* Headings are html elements, the main heading is an h1, then comes h2, h3, h4 and so on. You control an html element by simply writing the name in front of it */

h1 {
    text-shadow: 2px 2px 8px rgba(150, 150, 150, 1);
    color: rgba(119, 9, 121, 1);
}

/* In Joomla most buttons have the class btn-primary - in the element inspector you can check if the button you want to color really has this color.
*/

.btn-primary {
    background: rgba(119, 9, 121, 1);
}

/* If you want to color something, only if you move the mouse over it then write :hover after it
*/

.btn-primary:hover {
    background: rgba(0, 212, 255, 1);
}

/* In Joomla all article images have the class item-image, if you want to control only a specific image, then you have to give the image inside the article its own CSS class.
*/

.item-image {
    border: 2px solid #ff0000;
}


/*If you run into icons on the website, you can color them individually*/

.icon-user {
    color: #403678;

}

/* or you color all icons with this special statement*/

.fa, .fas, [class*=" icon-"], [class^="icon-"] {
    color: #403678;
}

/* The page footer of Cassiopeia has the class "footer" so you control it with .footer */

.footer {
    background: rgb(2, 0, 36);
    background: linear-gradient(90deg, rgba(2, 0, 36, 1) 0%, rgba(119, 9, 121, 1) 35%, rgba(0, 212, 255, 1) 100%);
}

Download .css File (zip)

More ressources to help you with CSS

Introduction to CSS
https://www.w3schools.com/css/css_intro.asp

Find colors/color codes:
https://coolors.co
http://colorsafe.co/
https://accessible-colors.com/
https://webaim.org/resources/contrastchecker/
https://www.google.com/search?q=colorpicker

Gradients with CSS
https://www.mediaevent.de/css/gradient.html
https://cssgradient.io/

Box shadow with CSS
https://cssgenerator.org/box-shadow-css-generator.html

Examples of different borders
https://developer.mozilla.org/en-US/docs/Web/CSS/border-style

Examples of styled lists
https://developer.mozilla.org/en-US/docs/Web/CSS/list-style-type

Free Fonts by google
https://fonts.google.com/

Add google fonts locally to your template
https://google-webfonts-helper.herokuapp.com/fonts

CSS Grid and Cassiopeia

Beside Bootstrap 5 Cassiopeia uses the modern css grid technique to define the layout of the website. To change the overall layout of the website you can also override the css grid statements with your user.css file.

You can use existing css grid classes from cassiopeia to define the layout of your blog view or article.

Settings for Blog Menu Item Type

The menu item type category blog has a parameter to insert one or more css classes. The classes are already defined in the Cassiopeia template and ready to use. You can add one or more of the listed classes into the leading article class or article class field.

Columns

columns-2
columns-3
columns-4
masonry-2
masonry-3
masonry-4

Styling

boxed

Image Location

image-left
image-right
image-bottom

Image Variation

image-alternate
Every second item, the image position is switched. If an image is set to the left, the image on the right will be displayed on every second item. If an image is set to the bottom, the image will be displayed at the top of every second item.

Reference

The explanation can be found here: https://github.com/joomla/joomla-cms/pull/18319

Position Article images

A Joomla article has a parameter to insert one or more css classes. The classes are already defined in the Cassiopeia template and ready to use.

Image Position

float-start
float-end

To use these classes for all articles, go to Content » Options » Editing Layout and enter the class you want in the "Full Text Image Class" field.

Master the css grid

For the CSS Veterans css grid is kind of a new technique - if you did not learn it yet it's really about time to dive into it. CSS grid is supported in all modern browsers and gives you unlimited freedom to define the layout and positioning of elemenent of your website.

Learn CSS grid first:

Fress CSS Grid Online Class by Wes Bos!

https://cssgrid.io/

Visit website

A nice reference for css grid in general can be found here:

https://css-tricks.com/snippets/css/complete-guide-grid/

Advanced Explanation on css grid for Cassiopeia
https://www.joomla51.com/blog/item/joomla-css-grid-and-dynamic-content

Grid Scss File of Cassiopeia for referende
https://github.com/joomla/joomla-cms/blob/4.0-dev/templates/cassiopeia/scss/blocks/_css-grid.scss

Cassiopeia demo page with help
https://cassiopeia.joomla.com/

Adding a custom JavaScript File to the Template

Same as adding a user.css file inside the css folder of your template you can add a custom Javascript file by creating an user.js inside the js folder.

Many thanks to Viviana Menzel, to Astrid Günther, to Hagen Graf for providing so many Cassiopeia resources that allowed me to write this tutorial, and of course to the entire Cassiopeia template team for their hard work.

Upcoming Updates in Joomla 4.1

There will be the possibility to create child templates in Joomla 4.1 + and the template manager view will be unified into one.
See https://github.com/joomla/joomla-cms/pull/30192 for details.

Test, Comment and discuss! Your involvement defines the future features, fixes and improvements. Log in into GitHub to be a part of Joomlas future.