Difference between revisions of "Gallery2:Themes" - Gallery Codex
Personal tools

Difference between revisions of "Gallery2:Themes"

From Gallery Codex

(Anatomy of a Theme)
m (Reverted edits by Angelanight (Talk) to last revision by Jabbba)
 
(69 intermediate revisions by 28 users not shown)
Line 1: Line 1:
{{expand}}
+
A theme is the outermost skin of Gallery. It's a thin but powerful layer that allows you to control almost every aspect of the user interface to make Gallery look exactly the way that you want. Gallery provides several themes to choose from and there are several user-contributed themes available to download and install. Gallery Administrators can choose which themes are available and set different themes for individual albums.
  
== What is a Theme? ==
+
There are several ways to customize how your Gallery looks. The first way is to select features to display in an installed theme in Gallery’s site administration area. Another way that to customize Gallery is to edit a theme’s template and style sheet files. The final way is to create your own theme—based on an existing theme or from scratch.<br/><br/>
  
A theme is the outermost skin of Gallery.  It's a thin but powerful layer that allows you to control almost every aspect of the user interface to make Gallery look exactly the way that you want.  Site Administrators can choose which themes are available in the Gallery, and then you can optionally choose a different theme for each album. Because themes are very powerful, not all themes provide the same functionality. For example, the Classic theme allows you to display a list of sub albums next to each album, functionality that's not available in other themes.
+
'''Select and Configure:'''
 +
* '''[[:Category:Gallery 2:Themes|Theme Catalog]]''' – A list of Gallery 2 standard and user-contributed themes, color packs, and icon packs.
 +
* '''[[Gallery2:Configuration:Themes|Managing and Configuring Themes]]''' – Information about installing, activating, upgrading, and configuring themes to change your Gallery’s appearance.
 +
'''Edit or Create a new one:'''
 +
* '''[[Gallery2:Themes:How_To|How Tos]]''' – A collection of step-by-step procedures to show you how to customize the look of your Gallery.
 +
* '''[[Gallery2:Themes:Theme_System_Overview|Editing and Creating Themes]]''' – An overview of Gallery 2’s theme system with detailed documentation showing how to edit and create theme templates and style sheets.
 +
'''Embed it:'''
 +
* '''[[Gallery2:Themes:Embedded_Theme_Considerations|Embedded Theme Considerations]]''' - Integrating Gallery with another application? This section is for you.
  
There are six different page types in Gallery.  A theme is responsible for understanding and drawing each of these different page types in a consistent way.
 
; Album : a page where you can view many photo thumbnails at once.  Typically you don't see any single photo in detail on these pages.
 
; Photo : a page where a single photo is displayed in detail.  Typically this page focuses on only one image, though it may show thumbnails of the other images around it.
 
; Module: pages that wrap content generated by modules that add additional functionality, like the slideshow and the members list.  The actual content of these pages is generated by the module itself (and can vary extensively). 
 
; Admin: pages that wrap content generated by the Gallery framework to administrate the site, items, or users.
 
; Error: a page that Gallery displays when something has gone wrong, giving the user instructions on how to proceed to correct the error (or whom to notify)
 
; Progress bar: a page that allows the theme to provide the user with some kind of visual indication that a long operation is in progress.
 
  
On Album, Photo, Error and Progress bar pages, the theme generates most of the HTML content that the user seesBut on Module and Admin pages, the theme receives chunks of HTML from Gallery modules and is expected to render those chunks in an style consistent with the rest of the site.  In order to make that possible, we have created a [[Gallery2:CSS Schema|CSS schema]] that we use consistently throughout the rest of the module HTML.
+
==Gallery 2 Templating System==
 +
Gallery's templating system is based on [http://www.smarty.net Smarty], a generic PHP templating system which uses separate template files to lay pages outGallery 2 customises this with several extra objects and variables.  The following pages describe the templating system in more detail:
  
Gallery also provides a system called [[Gallery2:Blocks|blocks]] which allow modules to provide themes with chunks of HTML that they can embed.  Blocks include functionality like displaying breadcrumbs, navigators, item comments, and random images.  The theme can choose where and when to embed blocks in a page, and can use CSS to control the appearance of each individual block.  In addition, the theme can allow users to configure which blocks are visible on the page by editing album settings.
+
*'''[[Gallery2:Themes:Reference:Smarty|Smarty]]''' - the template engine that assembles user- and Gallery-supplied content into the pages that are presented to the user
  
== Anatomy of a Theme ==
+
*'''[[Gallery2:Themes:Reference:Modifiers|Modifiers]]''' - modifiers can alter the way that Smarty presents text.  Gallery 2 extends the built-in ones with several that relate to display text in a gallery
  
A theme is composed of the following elements:
+
*'''[[Gallery2:Themes:Reference:Tags|Tags]]''' - Gallery 2 extends smarty with its own tags (e.g. ''{g->url ...}'') to provide useful shortcuts related to Gallery functions
; PHP : Themes comes with a small PHP file called '''theme.inc''' which is a thin glue layer between Gallery and your HTML templates. In this PHP file, the theme tells the Gallery framework what data it needs to show a page which allows Gallery to be efficient and only load the data that the theme requires.
+
; CSS : A theme will provide almost all the CSS that is used to draw a Gallery page. Themes provide their own custom CSS to make Gallery look any way they want.
+
; [[Smarty templates]] : These are files that contain a mixture of HTML and [[Smarty tags]] which allow you to craft your own HTML and use a little logic to draw the page. The theme is in charge of drawing most of the HTML on the page which gives it the flexibility to render the page in many different ways
+
; Images : Themes can provide their own images (or other data like Flash or Java applets)
+
; Localization files : Themes that provide language specific content can optionally use the Gallery framework to extract internationalized data so that our localization team can provide language specific versions.
+
  
== How do I customize a Theme? ==
+
*'''[[Gallery2:Themes:Reference:Blocks|Blocks]]''' - in the same way that blocks can be manipulated using the Site Admin interface in Gallery 2, they can also be used within a template by using the '''g->block''' function
  
* How do I create a brand new theme?
+
*'''[[Gallery2:Themes:Reference:Callbacks|Callbacks]]''' - callbacks are used to load data into blocks within templates using the '''g->callback''' function
* How do I clone an existing theme?
+
* How do I change the way a theme page looks?
+
  
== Creating a new theme ==
+
*'''[[Gallery2:Themes:Reference:Variables|Variables]]''' - Gallery 2 makes several variables accessible to a template which provide information about the current image, album, user and environment
  
The easiest way to create a new theme is by cloning a theme and then modifying it.
 
  
== Cloning a theme ==
+
[[Category:Gallery 2:Development:Themes]]
 
+
[[Category:Gallery 2:Usage]]
Pick a theme that is similar to the functionality that you want.  We suggest that you start from one of the themes that comes with Gallery2 itself as those are usually the most current code.  Your new theme will need a unique theme id.  Ids are a single word that contains only alphanumerics and underscores and should be related to the name of your theme.  So let's say that you're cloning the Matrix theme and making a new theme called ''MySite'', you might give it the id ''mysite''.
+
 
+
Let's start by making a copy of the the matrix:
+
 
+
  cd gallery2/themes
+
  cp -r matrix mysite
+
 
+
Now let's edit mysite/theme.inc to set the details for your new theme.  Edit mysite/theme.inc and inside you'll see a block that starts like this:
+
 
+
  class MatrixTheme extends GalleryTheme {
+
+
      /**
+
      * Constructor
+
      */
+
      function MatrixTheme() {
+
          global $gallery;
+
          $this->setId('matrix');
+
          $this->setName($gallery->i18n('Matrix'));
+
          $this->setDescription($gallery->i18n('Standard Gallery2 look and feel'));
+
          $this->setVersion('0.9.9');  /* Update upgrade() also */
+
 
+
You need to change every reference to ''matrix'' to ''mytheme'' so that it looks like this:
+
 
+
  class MySiteTheme extends GalleryTheme {
+
+
      /**
+
      * Constructor
+
      */
+
      function MySiteTheme() {
+
          global $gallery;
+
          $this->setId('mysite');
+
          $this->setName($gallery->i18n('My Site'));
+
          $this->setDescription($gallery->i18n('This is a theme for My Website'));
+
          $this->setVersion('0.9.0');
+
 
+
A few notes about this:
+
* You must use the same letters in the class name and function name as you use in the id, but the capitalization is not important.
+
* You can use whatever version number you want, but stick with the #.#.# format to make it easier for you to write your own upgrade code.
+
* If the original theme has an upgrade function, you can delete it from your new theme (and add it back later when you start supporting upgrades)
+
 
+
 
+
Now, go to the Site Admin and select the Themes option from the left sidebar.  Click on the "All Themes" tab and you should see your "My Site" theme show up in the list. 
+
 
+
Click the "install" link then the "activate" link and your theme should now be available for use!  Edit an album and select your theme from the list and you'll be using your own personal copy of the Matrix theme!
+
 
+
==External Links==
+
* [http://marc.theaimsgroup.com/?l=gallery-devel&m=111882332024437&w=2 Bharat's initial proposal] on the theme refactor
+
* [http://marc.theaimsgroup.com/?l=gallery-devel&m=112072316005756&w=2 Mail to the development mailing list] explaining the changes made.
+

Latest revision as of 15:18, 29 September 2010

A theme is the outermost skin of Gallery. It's a thin but powerful layer that allows you to control almost every aspect of the user interface to make Gallery look exactly the way that you want. Gallery provides several themes to choose from and there are several user-contributed themes available to download and install. Gallery Administrators can choose which themes are available and set different themes for individual albums.

There are several ways to customize how your Gallery looks. The first way is to select features to display in an installed theme in Gallery’s site administration area. Another way that to customize Gallery is to edit a theme’s template and style sheet files. The final way is to create your own theme—based on an existing theme or from scratch.

Select and Configure:

  • Theme Catalog – A list of Gallery 2 standard and user-contributed themes, color packs, and icon packs.
  • Managing and Configuring Themes – Information about installing, activating, upgrading, and configuring themes to change your Gallery’s appearance.

Edit or Create a new one:

  • How Tos – A collection of step-by-step procedures to show you how to customize the look of your Gallery.
  • Editing and Creating Themes – An overview of Gallery 2’s theme system with detailed documentation showing how to edit and create theme templates and style sheets.

Embed it:


Gallery 2 Templating System

Gallery's templating system is based on Smarty, a generic PHP templating system which uses separate template files to lay pages out. Gallery 2 customises this with several extra objects and variables. The following pages describe the templating system in more detail:

  • Smarty - the template engine that assembles user- and Gallery-supplied content into the pages that are presented to the user
  • Modifiers - modifiers can alter the way that Smarty presents text. Gallery 2 extends the built-in ones with several that relate to display text in a gallery
  • Tags - Gallery 2 extends smarty with its own tags (e.g. {g->url ...}) to provide useful shortcuts related to Gallery functions
  • Blocks - in the same way that blocks can be manipulated using the Site Admin interface in Gallery 2, they can also be used within a template by using the g->block function
  • Callbacks - callbacks are used to load data into blocks within templates using the g->callback function
  • Variables - Gallery 2 makes several variables accessible to a template which provide information about the current image, album, user and environment
advertisements