====== Themes ====== This page is dedicated to themes customization or themes creation. If you are looking for existing themes, refer to the documentation [[..:admin:themes|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.


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. 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 A specific class is assigned to the html tag for each context file and you can therefore change very easily how a specific context looks using this class. 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. 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 [[.themes:tags|in this section]]. How to create your own template tags is explained [[.:tpl|in that other section]]. ===== Annexes ===== {{{pagetoc .:themes:appendices }}}