How to create a theme

General information:

Compatibility: this tutorial is compatible with Piwigo 2.1 and higher
you can download themes from extensions section on piwigo.org

Introduction

On your photo gallery you will almost certainly want to change the color of a border, and then the width of a menubar and so on. You will thus probably modify a template file (themes/default/template/*.tpl files) or indeed several.

It's now time to stop modifying the standard themes and to start your own theme!

Don't panic, it's not complicated and it is very useful to have your own customization in a dedicated place, with no worry that you will lose it at the next upgrade.

Prepare

Let's say you want a new theme that is very close to the clear theme, but you want to change some colors. Let's call the new theme greenery

create a new directory themes/greenery
copy themes/clear/themeconf.inc.php into themes/greenery
create an empty themes/greenery/theme.css file

A theme needs at least 2 files theme.css and themeconf.inc.php.

themeconf.inc.php

In this file you define the theme properties.

<?php

/*
Theme Name: My greenery
Version: 0.1
Description: My very first theme
Theme URI: http://piwigo.org/ext/extension_view.php?eid=347
Author: John Do
Author URI: http://piwigo.org/
*/

$themeconf = array(
  'parent' => 'clear',
);
?>

The first block are comments (between /*...*/), but they must follow the syntax given in the example. The comment block is read by Piwigo to display information about your theme : 'Theme URI' is for automatic install/update from http://piwigo.org/ext.

Block 1 /*...*/

Key	Value	Description
Theme Name	My greenery	the name of your theme, any character is permitted
Version	0.1	Version number. If you use a SVN deposit on piwigo.org, set the Version to "auto" and this field will be set automatically when you create a new release on piwigo.org/ext
Description	My very first theme	A short description of your theme
Theme URI	http://piwigo.org/ext/extension_view.php?eid=347	Web address where you can find the theme on piwigo.org/ext
Author	John Do	Your own name
Author URI	http://piwigo.org/	The web address of your own website (advertisement purpose)

Block 2 : $themeconf

Key	Default value	Description
parent	default	The default theme is the base of all themes, but you can use another one. In the example, we use clear as parent theme. Required See more info below
icon_dir	themes/default/icon	Where are the icons of this theme?
mime_icon_dir	themes/default/icon/mimetypes/	Where are icons for non pictures files?
local_head	none	Path to a *.tpl file if you want to add HTML content into the <head></head> of each page. Useful to add inline javacript, Smarty code, CSS combined with Smarty...
activable	true	If you don't want your theme to be activable, set this value to false (this can be useful for parent themes adding only information on the layout)
load_parent_local_head	true	If you don't want this theme to load its parent local head, set this value to false
load_parent_css	true	If you don't want this theme to load its parent theme.css, set this value to false
use_standard_pages	false	If you want to use the standard pages design, set this value to true. If this is set to true you don't need to create login, register, forgotten password or profile pages.

theme.css

CSS rules only for this file. This is where you overwrite CSS rules inherited from the parent theme. Let's look at a small example:

FIELDSET, INPUT, SELECT, TEXTAREA,
#content DIV.comment  A.illustration IMG, #infos,
#content DIV.thumbnailCategory {
  border: 1px solid silver;
}

#comments DIV.comment BLOCKQUOTE {
  border-left: 2px solid #060;
  background-color: #ded;
}

#content UL.thumbnails SPAN.wrap2 {
  border: 1px solid #9a9;	/* thumbnails border color and style */
  -moz-border-radius: 4px;	/* round corners with Geko */
  border-radius: 4px 4px;	/* round corners with CSS3 compliant browsers */
}
#content UL.thumbnails SPAN.wrap2:hover {
  border-color: green;		/* thumbnails border color when mouse cursor is over it */
}

/* links */
A, .rateButton {
    color: #00895e;
    background: transparent;
}

A:hover {
    color: #458420;
}

Parent/child system

All theme.css and themeconf.inc.php of all parent themes are loaded. Of course, parents are loaded first, and the current theme last. The templates are loaded from the child theme, then from the parent themes. The system is recursive : let's take an visual example.

default theme | theme.css, themeconf.inc.php : loaded first | contains all tpl files
- dark theme | theme.css, themeconf.inc.php : loaded second | no tpl files
  - My dark theme | theme.css, themeconf.inc.php : loaded third | contains index.tpl

index.tpl will be loaded from "My dark theme", and the others from default

It's recommended to always add a parent theme, as the default.