Gallery3:Themes - Gallery Codex
Personal tools

Gallery3:Themes

From Gallery Codex

You might be looking for this: http://codex.galleryproject.org/Gallery_3:Themes or this: Gallery3:Tutorials:Themes

Disclaimer and Invitation

This page documents a part of Gallery3 that is being developed and is, therefore, changing. If you find any of this page inaccurate, you are invited verify and to edit it!

Initial Gallery 3 Theme Documentation Thread http://www.nabble.com/Re%3A-G3-Theme-Documentation-tt20495179.html#a20495179

How to use this Page

  1. Carefully, due to the changing nature of G3 at the moment.
  2. Note the section tagging.
    1. (DEV) intended for developers and coders. This includes sections on theory of operations and design.
    2. (THE) intended for themers - those who are willing to edit css, theme templates, etc.
    3. (USE) intended for users (non-coder) who only will change parameters in a GUI
  3. Edit this if you know something is inaccurate or not explained well, for the intended audience. If you cannot edit it, please let somebody know, since the success of G3 depends on your edits.

Overview - what is a theme - what a theme does and what it doesn't do. Reference overarching G3 overview doc.

Theme System Introduction

Gallery 3's theme system is the 'V'iew component of the Kohana MVC framework. The system's goals are to:

  • Promote UI consistency
  • Ease generation of new themes (replicate)
  • Be flexible and customizable (overrides for markup, css, color, etc.)
  • Simplify markup of module-generated content
  • Easily integrate in popular CMS UI's (WP, Drupal, Joomla, etc.)
  • Be RIA ready - Provide Ajax and DOM scripting "hooks"
  • Be easy to couple with CSS frameworks

How It Works

The following steps illustrate the basic steps Gallery takes to display an album page:

  1. The user clicks on a Gallery Album link which sends a request;
  2. Gallery reads the request and pulls thumbnail image information, metadata, and other related data for the page;
  3. Gallery core and related modules inject the raw album data into appropriate HTML markup blocks;
  4. Album HTML blocks are provided to the theme as PHP variables, some as strings, others, including the album's thumbnails, as arrays;
  5. The theme wraps the data in HTML markup to create a page layout templates, each template calls CSS and JavaScript.

All other pages follow roughly the same steps. Provide common HTML markup blocks as partials for module developers. Provide theme developers with the ability to override HTML partials...

Basic building blocks - basic behavioral technical stuff. reference standards documented elsewhere

css

Several tools provide gallery with sophisticated css behaviors - see the Toolsets section for more information.

  • css for layout - recommend grid tools
  • css for color and appearance - (document when strategy emerges)

tables

ajax

other

Toolsets - mandatory and optional - what does a themer need to know about the underlying code

Just as gallery is a tool available to the developer to manage media without programming from scratch, there are toolsets that allow the gallery team to provide certain functions without programming the basic functions. These toolsets are fully supported and documented by their respective authors.

kohana

kohana is an MVC framework, written in php. Gallery3 is a media management system, written in the kohana framework. Folks desiring to extend or alter Gallery 3 must know kohana. Kohana's home is http://kohanaframework.org/.

jQuery

CSS Reset

CSS reset allows gallery to more closely control layout and appearance by neutralizing browser css. There are several third party packages that provide css reset. the default theme uses YUI CSS Reset {Citation needed} which is documented at Yahoo's Developer site.

CSS Grid

CSS Grid tools allow sophisticated layout control. The default theme uses YUI Grids which is documented at Yahoo's Developer site.

other

Theme Structure and processing - discussion of the default theme and how it works.

File Structure (THE)(DEV)

  • A theme is stored entirely in ...galleryroot/themes/themename:
  • The subdirectories are
    • css (???)- contains the themes css files. each of these has a particular role, allowing control and modification. Remember that the default theme uses YUI Grids to control layout. The visual blocks can be placed in a widde variety of pre-set layouts as well as fully customizable ones without writing raw CSS.
    • images (optional) - the graphical elements used by the theme in formatting, decoration and control.
    • js (optional)- javascript specific to the theme (??)
    • views (required) - G3 is built in the kohana framework, where views are the bits used to control presentation of content. You may think of these as the (php) templates for the site. Depending on the nature of customizations, a knowledge of some kohana concepts (yui?) is needed.

The theming system works like this. (DEV) -- A (THE) version is needed

Access to an installation of the latest development version of G3 is helpful to understand this narration. It is currently built and deployed using a development scaffold which will be removed for production systems.

1) When you're viewing an album, we load up some basic data, and then look for a file called page.html.php.  This file lives in the theme (themes/default/views/page.html.php to be precise).  We specify that the "content" section of this page is a second file called album.html.php which also lives in the theme directory.  (and when you're viewing a photo, we specify photo.html.php).

2) page.html.php contains the basic outline for a page.  It references a header, sidebar and the main content (described above).  To load the header in page.html.php, we do:

   <?= $theme->display("header.html") ?> // This line seems not to exist anymore in the page.html.php--Jobaz 02:40, 10 March 2010 (UTC)

This loads up themes/default/views/header.html.php.  Notice that we don't mention the name of the theme in this line, or anywhere in the theme!  This means that you can copy a theme into a directory with a new name and have a brand new theme. // The default folder is non existent

3) Scattered throughout the various pages are references to "insertion points".  These are places where modules can insert their own HTML.  We have the following list of insertion points currently:

  • head
  • page_top
  • page_bottom
  • header_top
  • header_bottom
  • sidebar_top
  • sidebar_blocks
  • sidebar_bottom
  • album_top
  • album_blocks
  • album_bottom
  • thumbnail_top
  • thumbnail_bottom
  • thumbnail_info
  • photo_top
  • photo_blocks
  • photo_bottom

Each represents a specific spot on the page.  The theme marks that spot by putting a line like this into the html:

   <?= $theme->album_top() ?>

Then any module that wants to add something right above the album grid creates a file with a specific function in it.  So for example the slideshow module has a link at the top of the page so in modules/slideshow/helpers/slideshow_block.php we create a class called slideshow_block (actually slideshow_block_Core because of Kohana conventions, but that's not really important) containing a function like this:

  public static function album_top($theme) {     return "<a href=\"javascript:PicLensLite.start()\" id=\"gSlideshowLink\" class=\"gButtonLink\">Slideshow</\ a>";   }

When the theme calls <?= $theme->album_top() ?> it causes the slideshow module to insert its line of HTML.  So as soon as you add the slideshow module, the HTML appears in the right place on the page.

So with these insertion points, a module can very easily add stuff to the page.  Theoretically, themes can move these insertion points around, or even leave some out if it wants.  So as a module developer, the trick is to figure out where the insertion points are for a theme so that you can add stuff to the page.  For a theme developer, it's useful to see where the modules are adding their stuff.  To make all of this easier to understand, I created a new visual block mode for G3.  To use it, go to the [Info] tab in the scaffolding and turn on debug mode.  Then browse around and you'll see a UI like this:

http://galleryproject.org/gallery/screenshots/gallery3/theme_blocks.png.html

So you can tell what goes where on the page.  Adding an element to the page should now be as easy as creating two files (an installer file for your module and a block file for your module).  For example, all the slideshow code is here:

http://github.com/gallery/gallery3/tree/master/modules/slideshow/helpers/


 We provide a theme library with the following methods in it: // Where is that theme library? I found a Theme_View.php library in gallery3/modules/gallery/libraries but functions listed below are not there either.--Jobaz 02:40, 10 March 2010 (UTC)

url($path)

 Returns the url to a path inside the current theme.
 themes that use this won't have references to their own
 theme name in their files, which means you can just copy
 a theme dir to clone it
 example:
   <link ... href="<?= $theme->url("css/styles.css") ?>" />

item()

 Returns the current item we're viewing (album or photo).  Example:
   Album name: <?= $theme->item()->title ?>

display($file)

 Load up another file and display it.  Example:
   $theme->display("header.html")
 This will find the first file on the load path called header.html.php.
 The current theme's files will be used first, then the backup theme,
 then any modules.

blocks()

 Return an array of HTML blocks.  Currently used in sidebar.html.php
 like this:
    <? foreach ($theme->blocks() as $block): ?>
      <?= $block ?>
    <? endforeach ?>
 modules can register blocks and the theme will just run them in the
 right order.  Right now the block selection and order is hardcoded,
 and the block modules themselves are showing only mock data.

Take a look at the current theme files here: http://github.com/gallery/gallery3/tree/master/themes/wind/views/

A simple module that provides a block is here: http://gallery.svn.sourceforge.net/viewvc/gallery/gallery3/trunk/modules/carousel/helpers

A slightly more complex one is here: http://gallery.svn.sourceforge.net/viewvc/gallery/gallery3/trunk/modules/gmaps/helpers/ This link is out of date as the gmaps has been moved to its own module. Before going public it will need to be replaced by a relevant link to a more complex block code.

note that its HTML comes from here: http://gallery.svn.sourceforge.net/viewvc/gallery/gallery3/trunk/modules/gmaps/views/

Tutorials and HowTos

Modifying the Default Theme

This will change as G3 has more facility for managing themes through the admin interface.

Duplicate and deploy your copy of the default theme

Simple:

  1. Make a copy of the 'default' theme folder to 'mytheme'
  2. Edit /themes/mytheme/theme.info to change the description and title of your theme.

Details:
http://codex.galleryproject.org/Gallery3:Tutorials:Themes

You can now start modifying the the view templates in 'mytheme' under the 'views' directory as well as css files in 'css' directory.

Making appearance changes

  • How to control color in your theme
  • other

Making layout changes

  • How to include a block
  • How to change between liquid and fixed layouts
  • Placing navigation

New theme development

Required tools

  • Web developer addons for your browser.
  • Google Chrome
    • Right click the part of the page you are interested in and select 'inspect element' from context menu.
  • MS IE8 +
    • Press F12 on your keyboard.
  • FTP or SSH access to your web host.
  • A html editor or plain text editor.
  • Graphic editing package
  • A knowledge of HTML/CSS

Optional recommended tools

Discussion of alternate templating

Themes for G3

Gallery Core themes

The G3 product includes (several?) themes that can be used as-is, customized and used as the basis for new theme development.

  • default (scintillating name, doubt if anybody can do better :) )

default is YUI gridded theme that is meant to present albums in a workman-like manner. It is simple and direct. For many folks it will work as-is or with minimal color/layout adjustment. For others, it will provide a strong conformant basis for new theme development. There are tutorials on theme development that use default as the starting point. Anybody who plans on any level of theme development is advised to start there.

  • includedtheme2 Description goes here

Contributors

Many folks have made themes for Gallery. If you are looking for a look or functionality for your Gallery site, visit these sites to see what they have:

  • link 1
  • link 2
  • table of name/description of contributed themes?