Gallery2:Themes - Gallery Codex
Personal tools


From Gallery Codex

Revision as of 10:50, 12 July 2006 by Zimzat (Talk | contribs) (Category)


What is a Theme?

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.

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.

a page where you can view many photo thumbnails at once. Typically you don't see any single photo in detail on these pages.
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.
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).
pages that wrap content generated by the Gallery framework to administrate the site, items, or users.
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 sees. But on Module and Admin pages, the theme receives chunks of HTML from Gallery modules and is expected to render those chunks in a style consistent with the rest of the site.

Gallery also provides a system called 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.

Anatomy of a Theme

A theme is composed of the following elements:

Themes comes with a small PHP file called which is a thin glue layer between Gallery and your HTML templates or viewing application. 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.
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. A theme might consist of a single template with an embedded Flash application or Java applet.
A theme may contain JavaScript.
Themes can provide their own images.
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.

Anatomy of a Page

Each page displayed by Gallery is wrapped by a theme's theme.tpl template. This file wraps each of Gallery's page types. The contents of theme.tpl is decided entirely by the theme developer, but it is common for theme.tpl to contain the following elements.

DOCTYPE Declaration and root HTML tag 
First things first, a theme should declare which version of HTML or XHTML it conforms to and open the root html tag.
HTML head 
The document head adds content from Gallery and the selected theme. This content includes style sheet information, JavaScripts, metadata, and the HTML title for the page.
HTML body 
Open up the body so that the interface for a selected page may be displayed.
Theme banner 
Many themes place a banner to be displayed across all Gallery pages. Banners can contain, but are not limited to, logos, site menus, images, etc.
Bread crumb 
The links to help users return along their chosen path in Gallery.
Page content 
Render the chosen page--album, photo, admin, module, or progress bar. A bit of Smarty code detects which page has been requested and chooses the appropriate template file to insert at this point.
Theme footer 
The place for menus and all of that small legal print.
Gallery debug output 
Debug output displays messages for Gallery developers if the debugging module is enabled.
Close body and html tags 
End of file.

How do I customize a Theme?

  • How do I create a brand new theme?
  • How do I clone an existing theme?
  • How do I change the way a theme page looks?

Adding or creating a new theme

To add a theme, move it to the gallery/themes folder. For instance, if you have downloaded a zip file, unzip it and move the unzipped folder that contains the theme to the gallery/themes folder. The folder that contains the theme will have the files "" and "theme.css" in it. There are many User contributed themes available.

The easiest way to create a new theme is by cloning a theme and then modifying it.

Cloning a theme

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 matrix folder and all its contents, calling the new folder mysite. From a unix shell you can type:

 cd gallery2/themes
 cp -R matrix mysite

Or just use your ftp client to make a copy. For instance, you can copy the matrix folder to your computer, then rename it and upload it back to the server.

Now let's edit mysite/ to set the details for your new theme. Edit mysite/ and inside you'll see a block that starts like this:

 class MatrixTheme extends GalleryTheme { 

      * Constructor 
     function MatrixTheme() { 
         global $gallery; 
         $this->setDescription($gallery->i18n('Standard Gallery2 look and feel')); 
         $this->setVersion('0.9.9');  /* Update upgrade() also */ 

You need to change every reference of matrix to mytheme and adjust the description and version to be appropriate to your theme. These areas are marked below in bold:

 class MySiteTheme extends GalleryTheme { 

      * Constructor 
     function MySiteTheme() { 
         global $gallery; 
         $this->setName($gallery->i18n('My Site')); 
         $this->setDescription($gallery->i18n('This is a theme for My Website')); 

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 in this sense.
    • Capitalization is important in that the $this->setId('mysite'); must be the same capitalization as the folder name of your theme, otherwise you will get an error saying that it couldn't find your theme, when trying to install it. (so stick with the capitalization you use in your folder name)
  • 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)
  • Your theme name must end in "Theme" just as the matrix theme does.

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