Gallery2:Themes:How to Build a Theme.inc File

Each Gallery Theme has a PHP file named theme.inc. This file's purpose is to get data from the Gallery Framework to display album and photo information, such as titles, summaries, descriptions, and dates. The theme.inc file also allows theme developers to define their own display parameters and set default values for those parameters. Display parameters may include, but are not limited to, the number of items to show per album page, thumbnail dimensions, and page widths.

This document goes over the structure and purpose of the theme.inc file by discussing theme.inc considerations for the AutoRC theme.

Overview

Understanding the basics of what theme.inc does and the order in which it does it is important.

Theme.inc does the following:

Loads common Gallery data, including:
1. album data (titles, summaries, organization, etc.)
2. image data (titles, summaries, sizes, locations, etc.)
3. theme settings (blocks to show, etc.)
Loads additional data and transforms it for display in the theme, if necessary
Makes collected and transformed data available for use in the theme's template files

Structure of Theme.inc

The theme.inc file is PHP class file. For those unfamiliar with object-oriented programming a class is a set of functions, also known as methods, with similar purpose. The theme.inc file extends the GalleryTheme class which controls the display of information in Gallery.

A few facts about the theme.inc file:

Begins with the class declaration class AutoRcTheme extends GalleryTheme

  AutoRC stands for automatic rows and columns.

The class declaration consists of the theme's name, or abbreviation, followed by the word 'Theme'
The first function in the class is known as the constructor
The constructor's name must match that of the class
The class must contain certain methods present in GalleryTheme.class
You may add your own theme specific methods to the class

The names of the rest of the member functions should give a basic indication of their purpose. Look over the following skeleton theme.inc structure, We'll fill in the ... areas inside each function next. Text within the /** */ are comments and are not parsed.

  class AutoRcTheme extends GalleryTheme {
  
      /**
       * Constructor
       */
      function AutoRcTheme() {
        ...
      }
    
      /**
       * @see GalleryTheme::showAlbumPage
       */
      function showAlbumPage(&$template, $item, $params, $childIds) {
        ...
      }

      /**
       * @see GalleryTheme::showPhotoPage
       */
      function showPhotoPage(&$template, $item, $params) {
        ...
      }

      /**
       * @see GalleryTheme::showModulePage
       */
      function showModulePage(&$template, $item, $params, $templateFile) {
        ...
      }

      /**
       * @see GalleryTheme::showAdminPage
       */
      function showAdminPage(&$template, $item, $params, $templateFile) {
        ...
      }

      /**
       * @see GalleryTheme::showErrorPage
       */
      function showErrorPage(&$template) {
        ...
      }

      /**
       * @see GalleryTheme::showProgressBarPage
       */
      function showProgressBarPage(&$template, $item, $params) {
        ...
      }

      /**
       * @see GalleryTheme::getSettings()
       */
      function getSettings($itemId=null) {
        ...
      }

      /**
       * @see GalleryTheme::validateSettings
       */
      function validateSettings($settings) {
        ...
      }
  }

The Theme Constructor

The constructor method initializes, or enables, your theme and loads common data used throughout the theme. The constructor must also bring all of the essential data held in the $gallery variable, image file names, titles, captions, etc., by declaring it global in scope. Now, data in the $gallery variable may be used by the theme's functions.

  /**
   * Constructor
   */
  function AutoRcTheme() {
    global $gallery;

    $this->setId('autorc');
    $this->setName($gallery->i18n('AutoRC Theme'));
    $this->setDescription($gallery->i18n('Rows and columns that automatically adjust'));
    $this->setVersion('0.5.0');
    $this->setRequiredCoreApi(array(7, 0));
    $this->setRequiredThemeApi(array(2, 1));
    $this->setStandardSettings(array(
        'perPage' => 6,
        'sidebarBlocks' => serialize(array(
          array('search.SearchBlock', array('showAdvancedLink' => true)),
          array('core.ItemLinks', array('useDropdown' => false)),
          array('imageblock.ImageBlock', array()))),
        'albumBlocks' => serialize(array(
          array('comment.ViewComments', array()))),
        'photoBlocks' => serialize(array(
          array('exif.ExifInfo', array()),
          array('comment.ViewComments', array())))
          )
        );
  }

The constructor also:

Sets the theme's unique ID, which is stored in the database
Defines the theme's name, which is displayed in the plugin and theme admin areas
Sets the theme's version number, this number increases as the theme changes
Defines which version of Gallery the theme is compatible
Defines required theme API version required for compatibility
Sets standard settings for the theme, including which blocks to enable in the theme's sidebar, album, and photo display areas

The perPage index in the setStandardSettings array is a variable I've created for the AutoRC theme. Block parameters are set within sidebarBlocks, albumBlocks, and photoBlocks that define elements to add and details about how each element should be rendered.

There are many more things that you may add to setStandardSettings. Take a look at other themes' theme.inc files to see other possibilities.

Standard Methods, Method Structure, and Theme-Related Variables

The rest theme.inc's methods conform to the following standard structure.

Use a function to get, modify, or perform some action on Gallery data ( $ret = someFunction(); OR list ($ret, $someData) = somefunction(); )
Perform an error check ( if ($ret) { return array($ret, null); } )
If no errors occurred, return the template for the requested view return array(null, 'temaplateFileName.tpl');

The common variables, or arguments, accepted by theme.inc are:

$template: Holds all information made available to a theme's template
$item: Information about the album or photo requested, title, description, summary, etc.
$params: The theme parameters set for the requested album or photo, including which blocks to show, image size, the number of items to display per album page, etc.
$childIds: The ID numbers for each of the photos to display for a requested album
$templateFile: The required template file for the current request (album, photo, admin, etc.)
$settings: Custom parameters set by the theme

Now, let's examine AutoRC's theme.inc member functions.

showAlbumPage()

This function prepares and loads data to be displayed in the theme's album template. In Gallery, album templates display a set of photo thumbnails and details about each thumbnail. Usually, thumbnails and titles link to a detailed view for each item.

As with every other function in theme.inc, we only want to load the data needed by the album template. The AutoRC theme uses loadCommonTemplateData to load titles, the child item count, descendent item count, information about parent albums, links to the site admin and edit item views, item summaries, permission information, thumbnail settings, page navigation, and, of course, ids for the items to display.

 /**
    * @see GalleryTheme::showAlbumPage
    */
  function showAlbumPage(&$template, $item, $params, $childIds) {
    $ret = $this->loadCommonTemplateData(
        $template, $item, $params,
          array('title', 'childCount', 'descendentCount', 'parents',
        'systemLinks', 'itemLinks', 'itemSummaries', 'permissions',
        'thumbnails', 'pageNavigator', 'jumpRange'),
        $childIds);
    if ($ret) {
      return array($ret, null);
    }
    return array(null, 'theme.tpl');
  }

showPhotoPage()

  /**
   * @see GalleryTheme::showPhotoPage
   */
  function showPhotoPage(&$template, $item, $params) {
    $dataTypes = array('parents', 'systemLinks', 'itemLinks', 'permissions',
      'itemLinksDetailed', 'itemNavigator', 'imageViews', 'peerList', 'pageNavigator', 
      'jumpRange');
    $ret = $this->loadCommonTemplateData($template, $item, $params, $dataTypes);
    if ($ret) {
      return array($ret, null);
    }
    return array(null, 'theme.tpl');
  }

showModulePage()

  /**
   * @see GalleryTheme::showModulePage
   */
  function showModulePage(&$template, $item, $params, $templateFile) {
    $ret = $this->loadCommonTemplateData(
        $template, $item, $params, array('parents', 'systemLinks'));
    if ($ret) {
        return array($ret, null);
    }

    return array(null, 'theme.tpl');
  }

showAdminPage()

  /**
   * @see GalleryTheme::showAdminPage
   */
  function showAdminPage(&$template, $item, $params, $templateFile) {
    $ret = $this->loadCommonTemplateData(
        $template, $item, $params, array('parents', 'systemLinks'));
    if ($ret) {
        return array($ret, null);
    }
    return array(null, 'theme.tpl');
  }

showErrorPage()

  /**
   * @see GalleryTheme::showErrorPage
   */
  function showErrorPage(&$template) {
    return array(null, 'error.tpl');
  }

showProgressBarPage()

  /**
   * @see GalleryTheme::showProgressBarPage
   */
  function showProgressBarPage(&$template, $item, $params) {
    $ret = $this->loadCommonTemplateData(
        $template, $item, $params, array('parents', 'systemLinks'));
    if ($ret) {
        return array($ret, null);
    }

    return array(null, 'theme.tpl');
  }

getSettings()

  /**
   * @see GalleryTheme::getSettings()
   */
  function getSettings($itemId=null) {
    list ($ret, $settings, $params) = parent::getSettings($itemId);
    if ($ret) {
      return array($ret, null);
    }
    return array(null, $settings);
  }

validateSettings()

  /**
   * @see GalleryTheme::validateSettings
   */
  function validateSettings($settings) {
    $error = parent::validateSettings($settings);
    if (!is_numeric($settings['perPage'])) {
      $error['perPage'] = $this->translate('You must enter a number');
    }
    return $error;
  }

Personal tools