Coding guidelines for creating a theme (child theme or custom theme)

General information:

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

  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.

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 /*…*/

KeyValueDescription
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

KeyDefault valueDescription
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

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

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

File structure

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

 
Back to top
dev/extensions/theme_creation.txt · Last modified: 2013/03/08 14:37 by flop25
 
 
github twitter facebook google+ newsletter Donate Piwigo.org © 2002-2017 · Contact