Skip to content

Themes

Jump to bottom Edit New page
Johan Janssens edited this page Apr 23, 2021 · 53 revisions

Pages is built to work with any Joomla template out of the box and this will probably be the way you get started. If however you need more control or you are a designer who prefers to create custom designs Pages also offers the option to build a custom theme either for your whole site or only for specific pages.

Table of contents

Basics

Themes in Pages are quite simple and they allow you to customize your site’s presentation. Themes package up assets, stylesheets and javascript in a way that can be easily used in your site.

The real power when building your own custom themes comes from Joomlatools Mason, our batteries-included NodeJS task runner. Mason, comes with all the designer goodies your heart desires, it brings support for CSS transformations, automatic processing, live reload, and comes included with TailWindCSS.

Path of Least Resistance

You are 100% free to choose how to generate your CSS. If you don’t have a hard requirement, a strong preference, or just want our advice, we recommend writing your own HTML, using PHP in said HTML, use TailwindCSS as your CSS framework, and let Mason mix, transpile and minify any CSS and Javascript like there's no tomorrow.

Ofcourse there is nothing stopping you from using SCSS, Less, or even Bootstrap, or regular CSS. It simply comes down to your own personal preferences.

Structure

There are no set rules regarding the structure of a Pages theme. You can use any structure you like. We prefer the following simple and solid default:

/theme
  ├── css
  ├── js
  ├── fonts
  └── images

HTML document layout

Pages offers complete complete control over the generated HTML and can run outside of the context of Joomla. To do so you need to generate a complete HTML document. Pages will detect the presence of a <html> element and will output the page directly, and not forward it to Joomla for further processing.

To make this easy you can use following HTML5 document layout.

<!DOCTYPE html>
<html xmlns:og="http://opengraphprotocol.org/schema/" lang="<?= language() ?>" dir="<?= direction() ?>" vocab="http://schema.org/">
<head>
    <meta charset="utf-8"/>
    <base href="<?= url(); ?>" />

    <ktml:title>
    <ktml:meta>
    <ktml:link>
    <ktml:style>
    <ktml:script>

    <title><?= title() ?></title>

</head>

<body>

<ktml:content>

</body>
</html>

Put it in /joomlatools-pages/layouts/document.html.php and then include it in your pages frontmatter as follows:

---
layout: document
---

NOTE1: Do not edit this document layout. Pages will automatically replace the <ktml>placeholders for you, and set the language and direction attributes based on you page frontmatter. You include additional scripts, and stylesheets through your pages, and additional layouts.

NOTE2: This layout is being moved into the core as part of 0.21 release. For more info see following PR Extension template locator #369

Including static assets

Theme assets can very easily be included in your site using the theme:// url alias. Pages will replace this on the fly with the correct base path to your theme folder. For example:

Javascript

<script src="theme://js/scripts.js"></script>

Note: When adding scripts into layouts, they must be loaded into the body, not the head. If the kthml:script tag is present in the head of the layout it will collate scripts from the body of both layouts and pages.

Stylesheet

<link href="theme://css/styles.css" rel="stylesheet" />

Note: When adding stylesheets to layouts there are a couple of rules and constraints if adding them into the head of the layout:

  1. Internal stylesheets can be loaded using khtml:style
  2. External stylesheets cannot be loaded using khtml:style and must instead be loaded using the standard tag

Additionally, stylesheets loaded via khtml:style will be loaded first in the page ahead of stylesheets.

Image

<link href="theme://images/favicon.png" rel="icon" type="image/png" />

Process CSS with Joomlatools Mason

The real power when building your own custom themes comes from Joomlatools Mason, our batteries-included NodeJS task runner. It comes as a single binary with all dependencies included to perform common tasks for web development. Mason also doesn't pull in any files to your project folder. It's a portable binary that you can run from anywhere.

After you installed Mason and configured it you can run mason from the command line or mason inspect to see what options are available.

$ mason inspect

You can run the default tasks by just running mason. This will run CSS compilation and watch for changes.

$ mason
  ✔ Running css…
  ⠙ Watching for changes…

See also: Themes > Using Mason

Got a question or need help? We have a forum on Github Discussions where you can get in touch with us.

Clone this wiki locally