Gallery2:Themes:Anatomy of a Theme - Gallery Codex
Personal tools

Gallery2:Themes:Anatomy of a Theme

From Gallery Codex

Themes are composed of the following elements:

PHP (theme.inc) 
Each theme contains a PHP file, theme.inc. Theme.inc is the glue between the Gallery framework and a theme's HTML templates. This PHP file tells Gallery what data it needs to display a page. To make Gallery perform more efficiently, theme.inc should only request and load the data that the theme requires and nothing more.
Smarty Templates 
These files contain a mixture of HTML and Smarty template tags. Smarty templates allow you to craft your own HTML and use a bit of programming 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.
Cascading Style Sheets 
A theme will provide almost all the CSS used to draw a Gallery page. Themes provide their own style sheets to make Gallery look any way they want. Modules can also provide CSS to control Gallery elements, including blocks.
Blocks 
Gallery provides a block system that allows modules to provide themes with chunks of HTML to display. Blocks enable the display of breadcrumbs, menus, comments, and image blocks. Themes can choose where and when to display blocks on a page. Theme developers can use CSS to control block appearance. Themes can allow users to configure which blocks are visible by editing an album's site administration settings.

The following is a simple diagram illustrating the process of rendering an album page in Gallery 2. The process is similar for rendering individual photo and administration pages.

G2 theme diagram.png

Optional elements

  • Client-side scripts - A theme may contain JavaScript to add dynamic or interactive features.
  • 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.
  • Images - Themes can provide their own images which may be referenced directly within a template or as an icon pack.
  • Color packs - Gallery's color pack module is a means to change a theme's color pallette by adding a bit of CSS to change a theme's default text, link, and background colors. A theme can be designed to be compatible with color packs or provide its own color pack.
  • Image Frames - Adds frames around images in your Galleries.

Template Types

There are essentially six different template page types in Gallery. A theme is responsible for understanding and drawing each of these different page types in a consistent way.

Theme 
The core template required in all Gallery themes. Typically, theme.tpl displays common page elements, such as banners, site menus, and footers. The theme template usually includes and wraps other theme template files.
Album 
Displays a grouped set of image thumbnails.
Photo 
Displays a single photo and information about the photo. Typically this template displays just one item (image, movie, etc.), though it may show thumbnails of surrounding images.
Module
Wraps content generated by modules that provide specific features, like slideshows or member lists. The content for module pages is generated by the module itself.
Admin
Similar to Theme, admin.tpl wraps administrative views for the site, items, and users.
Error
The template that wraps content displayed when something has gone wrong. Error messages and instructions are generated and displayed by modules.
Progress bar
A simple template that displays visual progress during lengthy operations.

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.

Theme.tpl Template Structure

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 theme.tpl should normally contain some standard elements. Let's step through the Matrix theme's theme.tpl and highlight each of its parts.

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.
  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  <html>
HTML head 
The document head adds content from Gallery and the selected theme. This content includes style sheet information, JavaScript to load, metadata, and the title for the page.
    <head>
      {* Let Gallery print out anything it wants to put into the <head> element *}
      {g->head}
      
      {* If Gallery doesn't provide a header, we use the album/photo title (or filename) *}
      {if empty($head.title)}
        <title>{$theme.item.title|default:$theme.item.pathComponent|markup:strip}</title>
      {/if}
      
      {* Include this theme's style sheet *}
      <link rel="stylesheet" type="text/css" href="{g->theme url="theme.css"}"/>
    </head>

Here you can see some of the Smarty tags in use. Comments (which won't be displayed) can be embedded in {* ... *} tags:

  {* This is a comment
        ... and so is this. *}

Gallery has a whole slew of custom Smarty tags it uses to render different portions of the page. For example, {g->head} will pull in the common Gallery HTML <head> tag contents (such as JavaScript, meta tags, the title of the page, and external style sheets).

The {g->theme} smarty tag is used for two tasks. Here, it generates the correct URL to a file in your theme. So {g->theme url="theme.css"} will expand to display "themes/<your_theme/theme.css". You'll see the second {g->theme} task, including template files, in action just below.

Finally, you can see Smarty's {if ...} ... {/if} construct in use. We won't delve into the details too much, but the example above simply adds a fall-back <title> tag if Gallery didn't provide one.

HTML body 
Open up the body so that the interface for a selected page may be displayed.
    <body class="gallery">
      <div {g->mainDivAttributes}>
Full-screen modules 
Handle modules that require full control of the page.
        {*
         * Some module views (eg slideshow) want the full screen.  So for those, we
         * don't draw a header, footer, navbar, etc.  Those views are responsible for
         * drawing everything.
         *}
        {if $theme.useFullScreen}
          {include file="gallery:`$theme.moduleTemplate`" l10Domain=$theme.moduleL10Domain}
        {else}
          {*
           * ...
           * all of our content will go here
           * ...
           *}

Notice the special condition this theme uses to support full-screen modules (such as the slideshow). These modules will want full control of the page, so we just want to include the template for that module and return. Our content for the rest of the pages will be below in between the {else} ... {/if} tags.

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.
        <div id="gsHeader">
          <img src="{g->url href="images/galleryLogo_sm.gif"}" width="107" height="48" alt=""/>
        </div>

The Matrix theme displays a small Gallery logo in the top left of the page.

Bread crumb 
The links to help users return along their chosen path in Gallery.
        <div id="gsNavBar" class="gcBorder1">
          <div class="gbSystemLinks">
            {g->block type="core.SystemLinks"
                      order="core.SiteAdmin core.YourAccount core.Login core.Logout"
                      othersAt=4}
          </div>
          
          <div class="gbBreadCrumb">
            {g->block type="core.BreadCrumb"}
          </div>
        </div>

Here we see the first use of {g->block} tag. This tag is used to include other bits of HTML into your theme. Here we want to display the main system links and the navigation bread crumb. The core.SystemLinks block has a few custom attributes that allow you to modify how that block is rendered. The order attribute allows you to specify the exact order that the links are displayed. The othersAt attribute specifies where to place any other links not listed in order. In this case, we would like to insert any other links at position 4, so that the Logout button remains at the end of the list. The core.SystemLinks block also has a separator attribute, which allows you to specify some text or HTML to insert between each link in the list. See Gallery2:Themes:Reference#Blocks for a complete list of available blocks and their attributes.

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.
        {* Include the appropriate content type for the page we want to draw. *}
        {if $theme.pageType == 'album'}
          {g->theme include="album.tpl"}
        {elseif $theme.pageType == 'photo'}
          {g->theme include="photo.tpl"}
        {elseif $theme.pageType == 'admin'}
          {g->theme include="admin.tpl"}
        {elseif $theme.pageType == 'module'}
          {g->theme include="module.tpl"}
        {elseif $theme.pageType == 'progressbar'}
          {g->theme include="progressbar.tpl"}
        {/if}
Theme footer 
The place for menus and all of that small legal print.
        <div id="gsFooter">
          {g->logoButton type="validation"}
          {g->logoButton type="gallery2"}
          {g->logoButton type="gallery2-version"}
          {g->logoButton type="donate"}
        </div>
        {/if}  {* end of full screen check *}
      </div>

The {g->logoButton} tag is a shortcut for displaying some of those small Gallery buttons at the bottom of each page. Note that we then have the {/if}>/tt> tag which closes the <tt>{else} from our full-screen check above. Then we close the main div that we opened right after the <body> tag.

Gallery debug output 
Debug output displays messages for Gallery developers if the debugging module is enabled.
      {*
       * Give Gallery a chance to output any cleanup code, like javascript that
       * needs to be run at the end of the <body> tag.  If you take this out, some
       * code won't work properly.
       *}
      {g->trailer}
      
      {* Put any debugging output here, if debugging is enabled *}
      {g->debug}

We always want to render the trailer and debug blocks, even in full-screen mode, so we place them at the very bottom of the page. You'll probably want to leave these alone, as is.

Close body and html tags 
End of file.
    </body>
  </html>