General information:

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

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.

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

1. create a new directory “themes/greenery”
2. copy “themes/clear/themeconf.inc.php” into “themes/greenery”
3. create an empty “themes/greenery/theme.css” file

A theme needs at least 2 files theme.css and 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 /*…*/

Block 2 : $themeconf

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;
}

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 here, and the others from default

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

Here how a theme is structured and what file is required or optional, based on the default theme.

./themes/default
├─ fix-ie5-ie6.css specific to the default theme : defined in local_head.tpl
├─ fix-ie7.css specific to the default theme : defined in local_head.tpl
├─ fix-khtml.css specific to the default theme : defined in local_head.tpl
├─ iconset.css specific to the default theme : defined in theme.css
├─ index.php Recommended : used to redirect visitors from direct access to the folder
├─ local_head.tpl Defined in local_head.tpl : 'local_head'variable. Useful to add inline javacript, Smarty code, CSS&Smarty…
├─ print.css specific to the default theme : defined in local_head.tpl
├─ theme.css Required : put your CSS here
├─ themeconf.inc.php Required : see above for details
├─ <icon>Defined in themeconf.inc.php : 'icon_dir' variable. Put your favicon here, and see the list right above for required icons
│ ├─datepicker.png
│ ├─delete.png
│ ├─edit.png
│ ├─errors.png
│ ├─favicon.ico
│ ├─index.php
│ ├─infos.png
│ ├─note.png
│ ├─rating-stars.gif
│ ├─recent.png
│ ├─recent_by_child.png
│ ├─remove_s.png
│ ├─start_filter.png
│ ├─stop_filter.png
│ ├─validate_s.png
│ └─ <mimetypes>Defined in themeconf.inc.php : 'mime_icon_dir' variable. Used as representative picture for specific extensions.
│ ├─ …
├─ <images>Defined in themeconf.inc.php : 'img_dir' variable. Only ajax-loader-big.gif and ajax-loader-small.gif is used on the public part in piwigo 2.5+
│ ├─ ajax-loader-big.gif
│ ├─ ajax-loader-small.gif
│ ├─ colorbox-controls.png
│ ├─ colorbox-loading.gif
│ ├─ index.php │ ├─ progressbar.gif
│ ├─ progressbg_black.gif
│ ├─ progressbg_green.gif │ ├─ progressbg_orange.gif
│ ├─ progressbg_red.gif
│ └─ progressbg_yellow.gif
├─ <js> specific to the default theme : include jquery.min.js, jquery-ui and all the others javascript required by Piwigo. For your extensions refer to the scripts included here, and don't include your versions
├─ <s26>specific to the default theme : deposit of the default sprite with various color. Defined with .pwg-icon {background-image: url(s26/outline_808080.png);}
│ ├─ …
├─ <template>Optional : All the template files are written in Smarty. See “parent/child theme” paragraph above.
│ ├─ about.tpl
│ ├─ comment_list.tpl
│ ├─ comments.tpl
│ ├─ footer.tpl
│ ├─ header.tpl
│ ├─ identification.tpl
│ ├─ index.tpl
│ ├─ infos_errors.tpl New in 2.4
│ ├─ mainpage_categories.tpl
│ ├─ menubar.tpl
│ ├─ menubar_categories.tpl
│ ├─ menubar_identification.tpl
│ ├─ menubar_links.tpl
│ ├─ menubar_menu.tpl
│ ├─ menubar_specials.tpl
│ ├─ menubar_tags.tpl
│ ├─ month_calendar.tpl
│ ├─ navigation_bar.tpl
│ ├─ nbm.tpl
│ ├─ no_photo_yet.tpl Not required : only used at the first install, when there is no picture yet.
│ ├─ notification.tpl
│ ├─ password.tpl
│ ├─ picture.tpl
│ ├─ picture_content.tpl
│ ├─ picture_nav_buttons.tpl
│ ├─ popuphelp.tpl
│ ├─ profile.tpl
│ ├─ profile_content.tpl
│ ├─ redirect.tpl
│ ├─ register.tpl
│ ├─ search.tpl
│ ├─ search_rules.tpl
│ ├─ slideshow.tpl
│ ├─ tags.tpl
│ ├─ thumbnails.tpl
│ ├─ upload.tpl
│ ├─ <include>not used and deprecated. For instance, in picture.tpl : {* Example of resizeable {include file='include/autosize.inc.tpl'} *}
│ │ ├─ autosize.inc.tpl
│ │ ├─ colorbox.inc.tpl
│ │ ├─ datepicker.inc.tpl
│ │ └─ resize.inc.tpl
│ └─ <mail>
│ ├─ index.php
│ └─ <text>
│ ├─ index.php
│ ├─ <html>
│ │ ├─ cat_group_info.tpl
│ │ ├─ footer.tpl
│ │ ├─ global-mail-css.tpl
│ │ ├─ header.tpl
│ │ ├─ index.php
│ │ └─ notification_by_mail.tpl
│ └─ <plain>
│ ├─ cat_group_info.tpl
│ ├─ footer.tpl
│ ├─ header.tpl
│ ├─ index.php
│ └─ notification_by_mail.tpl
└─ <watermarks>Optional : only for 2.4+. Put your own watermark images in : only .png files.
├─ copyright.png
├─ Owned_Stamp.png
└─ Sample.png