🌍
English
Differences
This shows you the differences between two versions of the page.
|
dev:extensions:theme_creation [2012/11/03 17:56] tadjio A |
— (current) | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== Coding guidelines for creating a theme (child theme or custom theme) ====== | ||
| - | General information: | ||
| - | * Compatibility: this tutorial is compatible with Piwigo 2.1 and higher | ||
| - | * you can download themes from [[http://piwigo.org/ext|extensions section on piwigo.org]] | ||
| - | * you can test many themes on [[http://piwigo.org/demo|the demo]] | ||
| - | |||
| - | ===== Introduction ===== | ||
| - | |||
| - | On your photo gallery, you will certainly want to change the color of this border, and then the width of this menubar and so one. You will probably modify a template file (themes/default/template/*.tpl files) or 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 to loose it on 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. | ||
| - | |||
| - | <code php> | ||
| - | <?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', | ||
| - | ); | ||
| - | ?> | ||
| - | </code> | ||
| - | |||
| - | 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.\\ | ||
| - | |||
| - | |||
| - | __Bloc 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)| | ||
| - | |||
| - | __Bloc 2__ | ||
| - | ^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// | | ||
| - | |||
| - | ==== theme.css ==== | ||
| - | |||
| - | CSS rules only in this file. This is where you overwrite CSS rules compared to the parent theme. Let's see a small exemple: | ||
| - | |||
| - | <code css> | ||
| - | 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; | ||
| - | } | ||
| - | </code> | ||
| - | |||
| - | ===== 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. | ||
| - | |||
| - | <wrap smaller_line> | ||
| - | 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\\ | ||
| - | </wrap> | ||
| - | |||
| - | It's recommended to always add a parent theme, at least default. | ||
| - | |||
| - | ===== File structure===== | ||
| - | Here how a theme is structured and what file is required or optional, based on the default theme. | ||
| - | |||
| - | <wrap smaller_line> | ||
| - | ./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 \\ | ||
| - | </wrap> | ||