Themes

This page is dedicated to themes customization or themes creation. If you are looking for existing themes, refer to the documentation Blog look.

User guide for themes

General mechanics

Each theme is a set of files stored in a subdirectory of /themes on your Dotclear installation. Once interpreted by the template engine, those files will produce the HTML pages on the public side of your blog. Please find below details of the various files.

Organizing Files

Theme ID

The file named _define.php hosts the theme name, description, author and version number. It should preferably be written in english.

<?php
if (!defined('DC_RC_PATH')) { return; }
 
$this->registerModule(
        /* Name */                      "My Beautiful Theme",
        /* Description*/                "Two columns theme",
        /* Author */                    "annso",
        /* Version */                   '1.0',
);
?>

Fields of the function registerModule are commented in order to facilitate the understanding of this file. They are quite easy to understand so we will not explain them further.

Theme screenshot

If the theme directory contains a file called screenshot.jpg, this image will be displayed on the theme selection page. It provides an overview of the theme. The image must be 280 pixels wide and 245 pixels high.

The file templates or "contexts"

These files are stored in a subdirectory tpl in the theme folder.

Note:

Some themes, created before Dotclear RC1, may not follow that organization. just create the directory tpl and move the HTML files into it in order for the theme to work properly.

They will be used in the context of the page displayed:

home.html : news
post.html : a post
category.html : every post of a category
archive.html : list of months with posts
archive_month.html : all posts in a given month
tags.html : list of all tags
tag.html : all posts related to a tag
search.html : search results
404.html : error page

When a plugin creates another context, it must provide its own HTML file. This is the case, for example, of the dayMode and contactMe plugins.

Files included in the "contexts"

Some elements are recurring, in order to reuse them in every contextn they are created once and for all. These are the files whose name begins with an underscore, such as _footer.html.

_head.html : CSS & jQuery calls.
_top.html : the page header (not to be confused with the html header)
_footer.html : the page footer
_flv_player.html : the video player
_mp3_player.html : the mp3 player

Tip:

A specific class is assigned to the <body> html tag for each context file and you can therefore change very easily how a specific context looks using this class.

Tip:

You can always remove the call to an included file for a said context, then you can create a specific content for that context only. You may also create a _foobar.html or anything else that would suit your recurrent needs.

File priority

Dotclear will try to find the file it needs in the theme folder. If it does not exist there, it will be read from the default theme.

Note:

There is the specific case of the Atom & RSS feed templates. They are located in the /dotclear/inc/public/default-templates/ folder. You can customize those ones also by placing your own version in your theme's tpl folder.

So bear in mind that:

If you only want to modify one specific context, just copy its personalized file to you theme's tpl subfolder.
It is not necessary, and is even a bad idea, to create a theme by copying each and every template file of the default theme.

The template tags

Beside the well known xhtml tags, Dotclear template files use a specific syntax to call its own fuctions or display informations. Those tags and their attributes are listed and explained in this section. How to create your own template tags is explained in that other section.

Annexes

Kits de structures de thèmes