Themes are composed of the following elements:
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.
Optional elements
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.
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.
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 html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<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.
<body class="gallery">
<div {g->mainDivAttributes}>
{*
* 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.
<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.
<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.
{* 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}
<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.
{*
* 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.
</body> </html>
