BL4NK
BL4NK is a great starting point for a new Joomla!™ template project. It's a fully functional template (can be installed directly) and has responsive support. Internet Explorer is obsolete, HTML5 and CSS3 are the present. And that is how I build BL4NK. HTML5 tags can be used that all browsers correctly interpret. The CSS file Normalize.css is to all values neutral and independently to render by the browser. It is a advanced HTML5 alternative to the last CSS resets. All style sheets will be combined in one file and load compressed, which are compiled by Gulp before. The browser loads only a single CSS file with just one line. You can't get it any faster than that.
To write your CSS you can choose between LESS and SASS. Wait a moment, you don't know both? LESS and Sass are preprocessors of CSS. Similar to PHP and HTML you can write code with them that will put out clear CSS. You will use LESS or SASS to write CSS more effective. You can use variables, e.g. to use the same hexadecimal color values on different points. There are a lot of functions, also, and much more. We will get it later.
Then there is a BL4NK Bootstrap Edition (short BBE). For those of you who don't know Bootstrap: you should! Bootstrap allows you to design a template responsive with mobile-first strategy. If you are using the grid system your template will be responsive for desktops, tabletts and smartphones. Frameworks and APIs (Applications Programming Interfaces) make your life easier. If you are use them, your coding will be much faster as stand alone coding.

Features

  • Loading brutally fast
  • Start browsing through constant normalize.css
  • CSS compressor
  • Integrated LESS and SASS compiler
  • Support for desktops, tablets and smartphones
  • Own error, offline and print pages
  • Great icons in Bootstrap with Font Awesome

Photoshop files

Download psd.zip (10.8 MB) to create icons and preview images faster. The ZIP package contains the following files:
  • App Icon Template [2.0] .psd
  • template_preview.psd
  • template_thumbnail.psd
All files in Blank, starting with the most important file named index.php until favicon.ico will be explained in the following. However, as said by Sherlock Holmes: "To a great mind, nothing is little". And so it is. Every detail is important!
Following the Unix principle, each file is a text file and can be opened and edited with your editor. Okay, okay - for image files you'd rather use an image editing program.

File structure

Have you downloaded the Blank Template and unpacked, find you the following folders and files:
  • build
  • css
  • js
  • .gitignore
  • component.php
  • error.php
  • favicon.ico
  • gulpfile.js
  • index.php
  • logic.php
  • offline.php
  • package.json
  • README.md
  • template_preview.png
  • template_thumbnail.png
  • templateDetails.xml
Strictly speaking, you only need two files to create a working template:
  • index.php
  • templateDetails.xml
Combining these two files gives you Mini, the template with the smallest possible number of files. Follow the idea of minimalism further and look for the smallest index.php in the world.

index.php (Mini)

The index.php file is the core of the template. This makes all the files work together. It is crucial for the source code responsible and ultimately it's all about the source to create and influence.
The minimal structure of the index.php looks like this:
1
<?php defined('_JEXEC') or die; ?>
2
<!doctype html>
3
<html>
4
<head>
5
<jdoc:include type="head" />
6
</head>
7
<body>
8
<jdoc:include type="message" />
9
<jdoc:include type="component" />
10
</body>
11
</html>
Copied!
The first line is written in PHP. The good thing about PHP and HTML is that it can be written together. You can add PHP statements in an HMTL file, and vice versa. <?php opens a PHP statement - no matter where - and ?> closes it again. In the first line we forbid direct access to this file. This is done via the Joomla!™ API with the _JEXEC command. This statement checks if the file is being called from within a Joomla!™ session and it protects your site by making it more difficult for a hacker to damage your site.
On line two we declare with <!doctype html> the document type. This line is one of the many little improvements in HTML5. Before HTML5 cryptic document types had to be declared for each different version and every application. Long arcane lines of code, impossible to jot down from memory. This was necessary to ensure browsers correctly interpret the source code. With HTML5 that's over, because it is backward compatible.
What follows in line three, is the smallest possible construction of a HTML page. This page is opened with <html> and ends with </html>. The header section begins with <head> and ends with </head>. The body starts with <body> and ends with </body>. Within the header area while we load the header information with <jdoc: include type="head" /> from the Joomla!™ (API) in line five. This jdoc:include command will include the normal header information a website needs. It is a Joomla!™ statement that picks up the necessary bits from your Joomla!™ configuration. For example, the global metadata of the system load, the css stylesheets, JavaScripts and the RSS feeds.
The jdoc:include command you'll find twice more in the index.php: once as message type and then as a component type (on lines 8 and 9). In line eight we see <jdoc:include type="message" />, this makes the system messages work. Whenever Joomla!™ needs to talk to you, this line will show it on your screen. For example, if you send an email on a contact form, you'll see the message “your message has been successfully send” after you hit the send button.
Last item to discuss is <jdoc:include type="component" /> in line nine. This element should only appear once in the <body> element of the template to render the main content of the page with respect to the current page being viewed. So, enough explained. This is how the generated source looks like:
1
<!doctype html>
2
<html>
3
4
<head>
5
<base href="http://localhost/joomla/" />
6
<meta http-equiv="content-type"
7
content="text/html; charset=utf-8" />
8
<meta name="generator" content="Joomla! ..." />
9
<title>Home</title>
10
<link href="http://localhost/joomla/?view=featured"
11
rel="canonical" />
12
<link href="/joomla/index.php?format=feed&amp;type=rss"
13
rel="alternate" type="application/rss+xml"
14
title="RSS 2.0" />
15
<link href="/joomla/index.php?format=feed&amp;type=atom"
16
rel="alternate" type="application/atom+xml"
17
title="Atom 1.0" />
18
<link href="/joomla/templates/frontend/favicon.ico"
19
rel="shortcut icon"
20
type="image/vnd.microsoft.icon" />
21
<script src="/joomla/media/system/js/mootools-core.js"
22
type="text/javascript"></script>
23
<script src="/joomla/media/system/js/core.js"
24
type="text/javascript"></script>
25
<script src="/joomla/media/system/js/caption.js"
26
type="text/javascript"></script>
27
<script type="text/javascript">
28
window.addEvent('load', function() {
29
new JCaption('img.caption');
30
});
31
</script>
32
</head>
33
34
<body>
35
<div id="system-message-container">
36
<div id="system-message"></div>
37
</div>
38
<div class="blog-featured">
39
<div class="page-header">
40
<h1>Home</h1>
41
</div>
42
</div>
43
</body>
44
45
</html>
Copied!
The code begins with the document type <!doctype html> on line one. Followed by the <html> tag on line two. The next line, line three, begins the header information with <head>. Here the header information loaded (base, meta, title, link and script). In the body <body> to display a div an id="system-message-container" for system messages and the div class="blog featured" for the actual content. In the last div (line 25) the article title as the title as a first degree heading (h1) is generated.
This source-code comes from the default settings of a content-less Joomla!™ installation. The global meta-data (keywords and description) are not defined and are therefore not displayed. In the previous main-menu the entry "Home" is responsible for the title and heading. This entry is specified as a blog layout hence the class "blog-featured" with activated feed display. Therefore the links in the head-section are titled "RSS 2.0" and "Atom 1.0". On the remaining source-code - for now - you don't have an impact on the backend. At a later stage you will get a chance to take influence on the meta tag called "generator" with code snippets and to take out unneeded JavaScripts. Besides JavaScripts belong to the end of the HTML page before the closing body tag </body>. To increase performance, all JavaScripts should be loaded combined and compresses into a single file. There are exceptions, such as the JavaScript modernizr.js, which expressly is to be included in the head-section <head>. So much for the generated source code of the minimal index.php.

templateDetails.xml (Mini)

The file templateDetails.xml (note the capital D) is the second most important file after index.php within the template. The templateDetails.xml includes general template information (name, author, etc.) and defines the installation routine. The installation routine is nothing else than a listing of all folders and files that belong to the template, in order to have them unpacked and stored with the installation. Additionally the module positions are stored here in order to be integrated via the jdoc:include command in the index.php. Optionally, you can create parameters to make the template adjustable within the backend. Perhaps you want your template to shine in different colours, then you adjust those parameters. How about a pretty pink as in the BEEZ template (Joomla!™ 1.5), for example?
Now please, check out the minimum version of templateDetails.xml:
1
<?xml version="1.0" encoding="utf-8"?>
2
<!DOCTYPE install Public "-//Joomla! 2.5//DTD template 1.0//EN"
3
"http://www.joomla.org/xml/dtd/1.6/template-install.dtd">
4
5
<extension version="3.8" type="template" method="upgrade">
6
<name>mini</name>
7
<creationDate>14.01.14</creationDate>
8
<author>Alexander Schmidt</author>
9
<copyright>Copyright © 2018 Alexander Schmidt</copyright>
10
<authorEmail>[email protected]</authorEmail>
11
<authorUrl>https://alexanderschmidt.info</authorUrl>
12
<version>1.0.0</version>
13
<description>The smallest template ever.</description>
14
<files>
15
<filename>index.php</filename>
16
<filename>templateDetails.xml</filename>
17
</files>
18
<positions>
19
<position>debug<position>
20
</positions>
21
</extension>
Copied!
What do you see here? The first line creates (similar to PHP) an XML section determining version and character set (utf-8). Then comes, what a horror, the document type declaration. Here you will probably want to see the same concept, which was responsible for simplifying the document type in HTML5. But what do you find instead? A declaration, which you and I and the creators of XML simply could not write down from memory. Oh no! But luckily we have the BL4NK where everything is already pre-coded. Phew! Further explanations on this can be avoided as under the given joomla.org address there is no file to be found. And you're right if you ask yourself: Why bother?
Fine! Lets get to the fun part of templateDetails.xml. It begins with the install-section that includes the Joomla!™ version for which the template is determined. The type is called "template". The method="upgrade" allows the template to install over an existing version at a later stage (do you smell the danger?). Thereby newer versions of the files will be installed. However old files that are no longer needed will remain, thus will not be deleted. Next are the template's general information (template name, creation date, author, copyright, e-mail address, website, version and description) being displayed within the template manager in the Joomla!™ backend. After this the installation routine is listed. Folders <folder> and files <filename> are embedded belonging to the template. The module <positions> find their place hereafter. Each position is written on a separate line and is now ready to be integrated into the index.php. This file is also selectable via the module manager in the Joomla!™ backend.
If you would copy the two test files index.php and templateDetails.xml in a folder called mini and zip it into a file (.zip) you could successfully install this mini template in Joomla!™.
The mini template is not all suited as the starting point of your template development and is therefore going to be extended. Essential components of the extensions are:
  • LESS and SASS compiler
  • CSS files
  • error, offline and print pages

Cascading Style Sheets

The Cascading Style Sheets of Blank are located in folder css. If you open this folder, you find other files beside the css files:
  • custom.css
  • editor.css
  • error.css
  • normalize.css
  • offline.css
  • print.css
  • template.css
  • template.less
  • template.scss
The files template.less and template.scss are not css files. For what are these files?

template.less

LESS is a preprocessor of CSS. Or to say it with the official words: It's CSS, with just a little more.. So, you can write simple CSS in every LESS-file. Maybe for someone is CSS enough, but to build more complex templates imports, variables, functions, advanced selectors, mixins and a lot more could be usefull. You will get a very short overview of what LESS offers. For a deep dive read the official documentation.
By installing BL4NK you install the LESS compiler and the compiling process comes with Gulp. With Gulp you compile your less files into css. More on this later.
Let's take a look into template.less.
1
// FRONTEND LESS
2
// ==========================================================================
3
4
// This file will be used to generate the template.css
5
6
html {
7
}
8
9
body {
10
}
11
12
@media (min-width: 768px) {}
13
@media (min-width: 992px) {}
14
@media (min-width: 1200px) {}
Copied!
Well, "This file will be used to generate the template.css". There are only the comment at the first lines, two selectors html and body with no attributes and three media queries. This structure should give you the idea of the mobile first strategy. First you write your rules for mobile. If you do it well, there is no need to write other rules. This is called mobile only strategy. But maybe, there should display something in a different way, than you go with your definitions from mobile to tablett to desktop.

Imports

It is a good idea to put the styles of an object into a separate file and then import it to you main file. For example, if you want to design the navigation of a website, create a file called navigation.less. If it is created, you can import it to your template.less. The following statements can be used.
1
@import "navigation";
2
@import "navigation.less";
Copied!
There are also more options for @import At-Rules, which you can read in the official manual of LESS.

Variables

Often you need the same value some times in your CSS. Variables make it easier to controll those values from a single location.
1
@link-color: #B22222;
2
3
a {
4
color: @link-color;
5
}
Copied!
If you handle a lot of variables, it makes sense to put them in a separate file called variables.less.

Functions

You find a list of all built-in functions supported by LESS on the main manual. Here is a short example of the function to darken a color.
1
@link-color: #B22222;
2
@link-color-hover: darken(@link-color, 10%);
3
4
a {
5
color: @link-color;
6
}
7
8
a:hover {
9
color: @link-color-hover;
10
}
Copied!

Advanced selectors

With the ampersand & you can reference parent selectors the following way.
1
a {
2
color: @link-color;
3
&:hover {
4
color: @link-color-hover;
5
}
6
}
Copied!
Compiling this LESS results in
1
a {
2
color: #B22222;
3
}
4
5
a:hover {
6
color: #B22222;
7
}
Copied!

Mixins

You can mix-in class and id selectors.
1
.class, #id {
2
color: red;
3
}
4
.mixin-class {
5
.class();
6
}
7
.mixin-id {
8
#id();
9
}
Copied!
Results in
1
.class, #id {
2
color: red;
3
}
4
.mixin-class {
5
color: red;
6
}
7
.mixin-id {
8
color: red;
9
}
Copied!

template.scss

SASS is also a preprocessor of CSS. "Sass is the most mature, stable, and powerful professional grade CSS extension language in the world." SASS-files normally ends with .scss (in the past it was .sass, but with an upgrade it changes the ending). You can use imports, variables, functions, advanced selectors, mixins and a lot more. I will give you a short overview of what is possible. Take a look in the official documentation for deep diving.
By installing BL4NK you install the SASS compiler and the compiling process comes with Gulp. With Gulp you compile your less files into css. More on this later.
Let's take a look into template.scss.
1
// FRONTEND SASS
2
// ==========================================================================
3
4
// This file will be used to generate the template.css
5
6
html {
7
}
8
9
body {
10
}
11
12
@media (min-width: 768px) {}
13
@media (min-width: 992px) {}
14
@media (min-width: 1200px) {}
Copied!
Same like LESS above, "This file will be used to generate the template.css". There are only the comment at the first lines, two selectors html and body with no attributes and three media queries. This structure should give you the idea of the mobile first strategy. First you write your rules for mobile. If you do it well, there is no need to write other rules. This is called mobile only strategy. But maybe, there should display something in a different way, than you go with your definitions from mobile to tablett to desktop.

Imports

It is a good idea to put the styles of an object into a separate file and then import it to you main file. For example, if you want to design the navigation of a website, create a file called navigation.scss. If it is created, you can import it to your template.scss. The following statements can be used.
1
@import "navigation";
2
@import "navigation.scss";
Copied!
There are also @-Rules and Directives, which you can read in the official manual of SASS.

Variables

Often you need the same value some times in your CSS. Variables make it easier to control those values from a single location.
1
$link-color: #B22222;
2
3
a {
4
color: $link-color;
5
}
Copied!
If you handle a lot of variables, it makes sense to put them in a separate file called variables.scss.

Functions

You find a list of all built-in functions supported by SASS on the main manual. Here is a short example of the function to darken a color.
1
$link-color: #B22222;
2
$link-color-hover: darken($link-color, 10%);
3
4
a {
5
color: $link-color;
6
}
7
8
a:hover {
9
color: $link-color-hover;
10
}
Copied!

Advanced selectors

With the ampersand & you can reference parent selectors the following way.
1
a {
2
color: $link-color;
3
&:hover {
4
color: $link-color-hover;
5
}
6
}
Copied!
Compiling this SASS results in
1
a {
2
color: #B22222;
3
}
4
5
a:hover {
6
color: #B22222;
7
}
Copied!
Referencing Parent Selectors: & (follow the link)

Mixins

You can mix-in class and id selectors.
1
.class, #id {
2
color: red;
3
}
4
.mixin-class {
5
.class();
6
}
7
.mixin-id {
8
#id();
9
}
Copied!
Results in
1
.class, #id {
2
color: red;
3
}
4
.mixin-class {
5
color: red;
6
}
7
.mixin-id {
8
color: red;
9
}
Copied!

custom.css

This is a file for fixing styles in a fast way in the browser (Joomla!™ backend). It's bad to use it but sometimes you have to. So it is empty a ready for your fixes.
1
/* CUSTOM
2
========================================================================== */
3
4
/**
5
* In best case you don't use this file.
6
* It's for fast fixes in browser only.
7
*/
Copied!
Only the comment shows you which file you just opened.

editor.css

The editor.css file is used to display your own definitions in your Joomla WYSIWYG editor in the backend, if you use one. For example, the JCE editor. This is most popular editor, but there are many more. In the configuration of this editor it is possible to include your own stylesheets. And that's what we do.
1
/* EDITOR
2
========================================================================== */
3
4
/**
5
* This file is for backend editors like JCE.
6
* It will be used for print style, too.
7
*/
8
9
body {
10
background-color: #fff;
11
color: #000;
12
font: normal normal normal 75%/125% arial,sans-serif;
13
}
Copied!
By default, the text appears black on a white background. It is highly advisable to use the same definitions as in template.css. You may ask yourself: "why not assign the same template.css to the editor?” Well, that usually leads to an ugly editor screen. Also, only some sections of the template.css are responsible for the content. You don't need the remainder. That's why we define what you need in a separate file, without the initial IDs and container classes.

error.css

The file error.css is linked via the file error.php. Both files are used for the error output that appears when the user visits a non existent page (error 404). The standard Joomla!™ error 404 page is so ugly that it's necessary to code something better. Customized error pages are part of every good template and are therefore not something optional.
The default "error.css" definitions are as follows:
1
/* ERROR
2
========================================================================== */
3
4
html,
5
body {
6
height: 100vh;
7
}
8
9
body {
10
color: #111;
11
font-family: Arial,Sans Serif;
12
font-size: 1rem;
13
margin: 0;
14
padding: 0;
15
text-align: center;
16
}
17
18
#error {
19
margin: 0 auto;
20
padding: 20px;
21
max-width: 100%;
22
}
23
24
@media (min-width: 768px) {
25
#error {
26
padding-top: 32vh;
27
max-width: 400px;
28
}
29
}
30
31
h1 {
32
margin:0 0 20px 0;
33
}
34
35
.search label {
36
display:none
37
}
Copied!
The body are the background and typography defined. The padding is set to zero and output the contents are centered (text-align). The container with the ID #error then defines padding and width. The heading (h1) gets a smaller margin. The label of the search box is set not to be displayed (display:none).

normalize.css

The normalize.css file is a small CSS file written by Nicolas Gallaghers. It provides better cross-browser consistency of our HTML tags. It is a modern HTML5 compliant alternative to the traditional CSS reset. In more then 400 lines of code the HTML tags are defined. Look it over in your editor, when you have some free time. Don't mess around with it!

offline.css

Just like the error page, the file offline.css is linked within offline.php. The offline page will appear when Joomla is set offline in the global configuration. The visitor will then see the information as defined in this configuration. The appearance (our CSS definitions), is stored in this file.
1
/* OFFLINE
2
========================================================================== */
3
4
html,
5
body {
6
height: 100vh;
7
}
8
9
body {
10
color: #111;
11
font-family: Arial,Sans Serif;
12
font-size: 1rem;
13
margin: 0;
14
padding: 0;
15
text-align: center;
16
}
17
18
img {
19
border: 0 none;
20
}
21
22
#frame {
23
margin: 0 auto;
24
padding: 20px;
25
max-width: 100%;
26
}
27
28
@media (min-width: 768px) {
29
#frame {
30
padding-top: 32vh;
31
max-width: 400px;
32
}
33
}
34
35
.inputbox {
36
width: 130px;
37
}
38
39
form {
40
margin: auto;
41
}
42
43
form p {
44
margin: 0;
45
padding: 0;
46
}
47
48
form fieldset {
49
border: 0 none;
50
margin: 0;
51
padding: 0.2em;
52
}
53
54
input {
55
padding: 5px;
56
font-size: 1rem;
57
}
58
59
input.button {
60
cursor: pointer;
61
width: auto;
62
}
63
64
form p {
65
padding: 0.3em 0;
66
}
67
68
label[for="remember"] {
69
font-size: .85rem;
70
}
71
72
.alert {
73
padding: 15px;
74
margin-bottom: 20px;
75
border: 1px solid transparent;
76
background-color: #fcf8e3;
77
border-color: #faebcc;
78
color: #8a6d3b;
79
}
80
81
.alert h4 {
82
margin-top: 0;
83
margin-bottom: 10px;
84
color: inherit;
85
font-family: inherit;
86
font-size: 18px;
87
font-weight: 500;
88
line-height: 1.1;
89
}
90
91
.close {
92
float: right;
93
font-size: 21px;
94
font-weight: 700;
95
line-height: 1;
96
color: #000;
97
text-shadow: 0 1px 0 #fff;
98
filter: alpha(opacity=20);
99
opacity: .2;
100
}
101
102
.close:focus,
103
.close:hover {
104
color: #000;
105
text-decoration: none;
106
cursor: pointer;
107
filter: alpha(opacity=50);
108
opacity: .5;
109
}
Copied!

print.css

The print.css file is linked within the file component.php. Joomla offers to display the content as a print preview. This is done by clicking on the print icon. The icon's view can be set within the article options. Using this file enables you to define a printer-friendly output. You can, for example, increase the contrast of the text color to it's background to improve the readability. The background is best to be defined in white, to save printer ink.
In Blank the reset style sheet normalize.css is imported into the print.css file, also the file editor.css to create a printer-friendly version.
1
/* PRINT
2
========================================================================== */
3
4
@import url('normalize.css');
5
@import url('editor.css');
Copied!

template.css

In this file, CSS is written which is created by the LESS or SASS compiler generated with the help of your style sheet file template.less or template.scss. You don't need to edit the template.css file.

index.php (Blank)

It is and remains the core of every template: the file index.php. This is where all the files come together. The articles and modules created by you on the backend show up here. All on the right place of the page.

defined( '_JEXEC' ) or die;

This is my favorite command and should be on every Joomla T-shirt! This is a direct call to prevent manipulation by others. Only Joomla is allowed to execute the file containing this script.
1
<?php defined( '_JEXEC' ) or die;
Copied!
The PHP script remains open. Normally it would be closed with ?> but there there is more to follow.

logic.php

The logic.php file is not only explained separately (after the index.php file described here), but also included.
1
include_once JPATH_THEMES.'/'.$this->template.'/logic.php';
Copied!
The logic.php file is included exactly once with the command include_once and integrated and executed as PHP script. Joomla specifies the path to the templates into JPATH_THEMES. Then it goes on with a slash (/) and the folder of the actual templates in $this->template inserted in the variable. Another slash and the file name logic.php form the end. Perhaps it would be easier to write the path directly.
1
include_once 'templates/frontend/logic.php';
Copied!
However, this notation is error-prone. Just remember, if you renaming the template to mytemplate from frontend. In this case, you should know that you have to change the path in index.php. That's it. We close the area of PHP with ?>.

Document type

Now we leave the PHP part behind us and have a look at the HTML area. Starting with the document type. Old fogies like myself still remember the complexity of this tag in days gone by. Depending on which "dialect" was spoken, whether HTML 4 or XHTML 1.1, whether or strict standard, you had set a correct lengthy and complicated line of code. That's fortunately over in HTML5:
1
<!doctype html>
Copied!
Cool!

html

We open the Hyper Text Markup Language document with the <html> tag and it is closed with </html>. Therein is the header <head> part and the body <body> part.
In your head, in your head Zombie, zombie, zombie Hey, hey What's in your head, in your head Zombie, zombie, zombie Hey, hey, hey Oh, do, do, dou, do, do, dou, do, do Dou, do, do, dou, dou, do, do, dou (Part of the songtext: The Cranberries - Zombie)
Everything within <head> and </head> are part of the header of the HTML document.

Header information

Through the interface of Joomla!™, called the API (Application Programming Interface), we can use the header information:
1
<jdoc:include type="head" />
Copied!
This will load the page title, all CSS files and JavaScripts and extensions are loaded (and more, but we'll not worry about that). Yes, you read it right. JavaScript ... In head ... Head shot. And every good frontend developer know: JavaScript should be at the end of the index before the closing body-tag </body>. But anyway, we do not use this way, hehe.

Viewport

The mobile view of your site is supported so that view (viewport) of your browser shows the correct viewport.
1
<!-- mobile viewport -->
2
<meta name="viewport"
3
content="width=device-width,
4
initial-scale=1.0,
5
maximum-scale=1.0,
6
user-scalable=0" />
Copied!
The above code sets the correct width.

body

All that stands between the <body> and </body> is shown to the visitors of your site. This is the place for your layout structure. This is where the actual content of your website takes shape. In BL4NK this area relatively empty. For the start there are two includings. One type component to display the articles for example and the debug module. And yes, before the closing body-tag </body> we put our awesome uglified and full compressed javascript file to rule all our javascript. This is the best case we can have.

page class

The body tag gets two classes added so that you later can define your CSS more precisely.
1
<body class="<?php echo $active->alias . ' ' . $pageclass; ?>">
Copied!
Let's start from the end: The variable $pageclass is declared in the file logic.php (more on that later). It is in the backend of Joomla!™, in each menu item to be specified in options and is quite handy for your own layouts. The variable $active->alias is the alias of each menu item displayed.

Debug module

The debug module is necessary for troubleshooting. If you turn the debug mode on in Joomla!™ (in the global configuration), this module outputs the database query that many developers - you, amongst others - find helpful. The debug module is the only module included in Blank. Just as any other module the position must be defined in templateDetails.xml. The name debug is compulsory. I usually place it as the last item in the <positions> section of templateDetails.xml:
1
<positions>
2
<position>debug</position>
3
</positions>
Copied!
Now the position is available, and the module can be used by the index.php. This is done by Joomla!™ API with the jdoc:include command. At the end of index.php, before the closing body tag, you find the following line:
1
<jdoc:include type="modules" name="debug" />
Copied!
This line causes the debug mode to be switched on and the output of it to be shown (when required) in the browser window. You need to do the same with all your module positions. For example, if you want to create the module positions header, navigation, breadcrumbs, you write in the templateDetails.xml:
1
<positions>
2
<position>header</position>
3
<position>navigation</position>
4
<position>breadcrumbs</position>
5
</positions>
Copied!
And in the index.php on the places where you want them to appear:
1
<jdoc:include type="modules" name="header" />
2
<jdoc:include type="modules" name="navigation" />
3
<jdoc:include type="modules" name="breadcrumbs" />
Copied!
That finished the module positions. From now on, all modules are assigned the the correct position. In the backend (Extensions> Modules> Site) - thanks templateDetails.xml. And in the frontend - thanks to index.php.

Module Chrome

Module chrome belongs, together with overrides, to Joomla!™'s special features. It makes the system very flexible for web developers. Module chrome and overrides are some of the reasons why Joomla!™ is so powerful. In addition to the type and name the jdoc:include command gives you also the attribute style. This allows to control the output of a module. We have the following values available:
  • none
  • xhtml
  • outline
  • rounded
  • table
  • horz
With these values, you can significantly influence the output. This chrome value (please do not confuse with the likewise named browser from Google) lets the system know how the module should be rendered. Joomla!™ also enables you to define your own chrome variables. The above values in detail:

none

Command:
1
<jdoc:include type="modules" name="menu" style="none" />
Copied!
Output:
1
<ul class="menu">
2
<li><!-- menu items --></li>
3
</ul>
Copied!

xhtml

Command:
1
<jdoc:include type="modules" name="menu" style="xhtml" />
Copied!
Output:
1
<div class="moduletable">
2
<h3>Main Menu</h3>
3
<ul class="menu">
4
<li><!-- menu items --></li>
5
</ul>
6
</div>
Copied!

outline

Command:
1
<jdoc:include type="modules" name="menu" style="outline" />
Copied!
Output:
1
<div class="mod-preview">
2
<div class="mod-preview-info">left[outline]</div>
3
<div class="mod-preview-wrapper">
4
<ul class="menu">
5
<li><!-- menu items --></li>
6
</ul>
7
</div>
8
</div>
Copied!

rounded

Command:
1
<jdoc:include type="modules" name="menu" style="rounded" />
Copied!
Output:
1
<div class="module">
2
<div>
3
<div>
4
<div>
5
<h3>Main Menu</h3>
6
<ul class="menu">
7
<li><!-- menu items --></li>
8
</ul>
9
</div>
10
</div>
11
</div>
12
</div>
Copied!

table

Command:
1
<jdoc:include type="modules" name="menu" style="table" />
Copied!
Output:
1
<table cellpadding="0" cellspacing="0" class="moduletable">
2
<tr>
3
<th valign="top">Main Menu</th>
4
</tr>
5
<tr>
6
<td>
7
<ul class="menu">
8
<li><!-- menu items --></li>
9
</ul>
10
</td>
11
</tr>
12
</table>
Copied!

horz

Command:
1
<jdoc:include type="modules" name="menu" style="horz" />
Copied!
Output:
1
<table cellpadding="0" cellspacing="0" class="moduletable">
2
<tr>
3
<th valign="top">Main Menu</th>
4
</tr>
5
<tr>
6
<td>
7
<ul class="menu">
8
<li><!-- menu items --></li>
9
</ul>
10
</td>
11
</tr>
12
</table>
Copied!

custom chrome

As already mentioned, it is possible to define your own output, thus own chrome variables for the style attribute. The BL4NK contains the file modules.php found in the html folder of the template directory. As you may have noticed, in BL4NK there is neither the said folder (html), nor the said file (modules.php). Have you installed the template, you can safely create the folder and create the file inside this folder. If you stand before the installation, then the reference to the newly created folder belongs to the templateDetails.xml, so that the installation routine of Joomla!™ knows that this folder exists. Otherwise the folder wouldn't be installed. For details see the chapter templateDetails.xml.
If you create the modules.php file in also new created folder called html, the content could look like this:
1
<?php defined('_JEXEC') or die;
2
3
function modChrome_mystyle($module, &$params, &$attribs) { ?>
4
<div class="moduletable
5
<?php echo htmlspecialchars($params->get('moduleclass_sfx')); ?>">
6
<div class="bghelper">
7
<h3><?php echo JText::_( $module->title ); ?></h3>
8
<div class="modulcontent">
9
<?php echo $module->content; ?>
10
</div>
11
</div>
12
</div><?php
13
}
14
15
?>
Copied!
This chrome can be controlled throught the value mystyle. Important in creating your own chrome features is the transfer of $module, &$params and &$attribs to bring the settings, parameters and attributes to each module, e.g. title, content, module class suffix and so on.
Chrome and overrides are the reasons why Joomla!™ is the right system for your web project.

logic.php

The logic.php file is included in the index.php. While the index.php stands for the HTML output, the logic.php represents the programming logic. During template development, it is not unusual that the file is further programmed.

defined( '_JEXEC' ) or die;

To make sure that this file is called only in Joomla!™, this line is written.
1
<?php defined( '_JEXEC' ) or die;
Copied!
This code prevents that the file can be accessed from the address bar of your browser.

Declaring variables

Some variables for the proper use of the template are required. The basics of PHP variables can be found in PHP manual (for beginners: A simple tutorial in PHP).
In a nutshell:
  • The first character of each PHP variables is the dollar sign $. This is followed by the variable name.
  • Distinction is made between uppercase and lowercase.
  • $My_variable is not the same as $my_variable or $My_Variable.
  • The dollar sign must be followed by a letter or an underscore (_).
  • Spaces are not allowed. $_my_variable is okay, $ my_variable is not.
1
// variables
2
$app = JFactory::getApplication();
3
$doc = JFactory::getDocument();
4
$menu = $app->getMenu();
5
$active = $app->getMenu()->getActive();
6
$params = $app->getParams();
7
$pageclass = $params->get('pageclass_sfx');
8
$tpath = $this->baseurl.'/templates/'.$this->template;
Copied!
Most of the variable names are quite self-explanatory. Not so for the contents of the variables, a little explanation is in order. Let's go line by line:
1
$app = JFactory::getApplication();
Copied!
Here the variable $app is first created, the content in the Joomla!™ framework is called for by the JFactory. The application to which it refers to is Joomla!™ itself, the CMS. The variable $app we will also need for the parameters.
1
$doc = JFactory::getDocument();
Copied!
Similarly, the variable $doc. Again, we put about the Joomla!™ framework to work with the JFactory class. This variable will take care of the RSS feeds within the page, site information, such as the title and description, references to the JavaScript and CSS files being loaded and will do a lot more. However, that is beyond the scope of this book.
1
$menu = $app->getMenu();
Copied!
This variable asks for the menu from the $app variable.
1
$active = $app->getMenu()->getActive();
Copied!
This variable goes a step further: it looks for the active menu item within the $menu. It also checks if this is the Home page or not.
1
$params = $app->getParams();
Copied!
Using the variable $app we'll query Joomla!™ for the parameters and store that in the variable $params. We will then use to query the page class:
1
$pageclass = $params->get('pageclass_sfx');
Copied!
A rather aptly named variable, $pageclass. The Page Class Suffix is a parameter in Joomla!™ Menu Items. It is set in the Menu Item: [Edit] screen under the "Page Display" section. This will order Joomla!™ to either add a new CSS class or modify the existing CSS class for elements in this specific Menu Item layout.
1
$tpath = $this->baseurl.'/templates/'.$this->template;
Copied!
That's easy: Variable $tpath contains the relative path to the template directory from the base URL. The $tpath variable is told to look for the active template folder from the base url.
These are all the variables used in Blank.

generator tag

The generator tag tells the world that we build this site with Joomla!™. Something nobody needs to know, least of all undesirables who want to hack your site. Do we want it? No, we most certainly do not!
1
$this->setGenerator(null);
Copied!
We are the web developers and we are the ones that need to know what the source code actually is. Nobody else should. Hackers need to know what CMS your using, in order to hack it. Why make it any easier than necessary?
Supposing your want to want to tell the world your website runs on Drupal or WordPress? No problem. Just fill in Drupal or WordPress between the single quotes. Or anything that you like:
1
$this->setGenerator('Drupal');
Copied!
This will generate <meta name="generator" content="Drupal" /> in the outputted source code of your website.

unset

The following lines are all comment out and have no effect right now. Maybe it will be neccessary to comment the lines in to unset some scripts, e.g. jquery. What happened if you comment the following lines in?
1
// unset
2
unset($doc->_scripts[$this->baseurl .'/media/jui/js/jquery.min.js']);
3
unset($doc->_scripts[$this->baseurl .'/media/jui/js/jquery-noconflict.js']);
4
unset($doc->_scripts[$this->baseurl .'/media/jui/js/jquery-migrate.min.js']);
5
unset($doc->_scripts[$this->baseurl .'/media/system/js/caption.js']);
6
if (isset($doc->_script['text/javascript']))
7
{
8
$doc->_script['text/javascript'] = preg_replace('%jQuery\(window\)\.on\(\'load\'\,\s*function\(\)\s*\{\s*new\s*JCaption\(\'img.caption\'\);\s*}\s*\);\s*%', '', $doc->_script['text/javascript']);
9
$doc->_script['text/javascript'] = preg_replace("%\s*jQuery\(document\)\.ready\(function\(\)\{\s*jQuery\('\.hasTooltip'\)\.tooltip\(\{\"html\":\s*true,\"container\":\s*\"body\"\}\);\s*\}\);\s*%", '', $doc->_script['text/javascript']);
10
if (empty($doc->_script['text/javascript']))
11
{
12
unset($doc->_script['text/javascript']);
13
}
14
}
Copied!
Well, the first line is a comment. The second line unset the file jquery.min.js from head, the third line jquery-noconflict.js, the fourth (may the 4th be with you) line jquery-migrate.min.js and the fifth caption.js. The lines after that unset all direct written javascript in head. With these lines helps you to bring all scripts in only one file.

Template CSS

To access the one and only template css, you only need this lines:
1
// css
2
$doc->addStyleSheet($tpath.'/build/style.css');
Copied!

Custom CSS

The line to add the custom css is comment out. Comment in, if neccessary.
1
// $doc->addStyleSheet($tpath.'/css/custom.css');
Copied!
This will load the custom.css in the head for faster style fixings.

Parameter

The template engine is one of the great strengths of Joomla!™. It is possible to gain more flexibility in your template with parameters. For example, you can set different color variations for your template in the backend. These settings are stored as styles in the database. A style is a single definition of settings for your template. You can define multiple styles and assign one to a menu item.

Definition

Parameters are defined in the templateDetails.xml. However, BL4NK comes with no parameters. For example, here you see a parameter that inserts a Google font in your template:
1
<config>
2
<fields name="params">
3
4
<fieldset name="basic">
5
6
<!-- GOOGLE FONT-->
7
<field name="googlefont" type="text" default=""
8
label="Google Font"
9
description="font type input">
10
</field>
11
12
</fieldset>
13
14
</fields>
15
</config>
Copied!
For the parameters to work you need to set them in <fields name="params"></fields>, which you can find between <config> and </config>, in the configuration (config) section. You create in the fields tag the space for specifying the parameters. With the fieldset tag you group the parameters. Each parameter is defined within a field tag (please observe: without s). To this very day, attributes of type and name are mandatory. All other attributes are optional.
A Google Font is of the type text. You can enter any text. In the label name you set the title for the parameter, visible in the backend. In description you place the text which will be visible when you hover over the title in the backend.

type

specifies the HTML element we want. In this case "text". There are many different standard parameter and form field types supported in the Joomla!™ Framework for all extension types (templates, components, modules and plugins).

name