Table Of Contents

1. Methods
2. Editing current theme HTML
3. The easy way, simmer_theme from graphics.
4. From scratch, Theme API
5. Submitting Themes
6. Converting v2.0 Themes to v3.0 Themes

1:   Methods

There are easy ways and complicated ways to create a custom theme,
depending on what you want to be able to do.

2:   Editing current theme HTML

If you just want to slightly change the theme to match the output
of your site, it might make sense to edit a current theme.
In the theme directory there are two *.th files.  album.th is
the template for album pages (the thumbnail pages) and image.th
is the template for image pages (where you can see medium or full
size images).  The files are very similar to HTML except for
some embedded <: ePerl :> code.  Even if you don't know perl or
ePerl you can still edit the HTML to make simple changes.

Good starting themes:

Any simmer_theme is going to be up to date and clean, such as "Blue" or
"Maste."  If you only need 4 corner thumbnail borders then take a look
at "Eddie Bauer."  If you want overlay/transparent borders, see FunLand.

If you want something demonstrating a minimal amount of code, try "simple"
but be warned that I haven't touched the theme in a long time.

3:   The easy way, simmer_theme from graphics.

Most themes have the same basic form, show a bunch of thumbnails
for directories and then for images, with a graphic border, line and
background.  If this is what you want, but you want to create new
graphics, then there is a tool that will build your themes for you.

If you create a directory with the images and a CREDIT file as well
as a Font or Style.css file, then simmer_theme will create theme for you.

Files:

Font/Style.css
This determines the fonts used by the theme.  The "Font" file is the
older system, documented below.  Create a Style.css file and define
styles for: body, title, main, credit and anything else you like.

See FunLand for a simple example.

Alternatively, use a font file.  An example Font file is:

--------------------------------------------------
$TITLE_FONT = "size='4' color='#ffffff' face='Times New Roman,Georgia,Times'";
$MAIN_FONT = "face='Times New Roman,Georgia,Times'";
$CREDIT_FONT = "size='-1' face='Verdana' color='#ffffff'";
$BODY = "background='$PATH/bkgrnd.gif' link='#0099FF'">
--------------------------------------------------

CREDIT
The credit file is two lines and is used for the theme index at MarginalHacks.
If you're never submitting your theme to us, then you don't need this file.
(But please do!)  If so, the two lines (and only two lines) are:

1) A short description of the theme (keep it all on one line)
2) Your name (can be inside a mailto: or href link)

Null.gif
Each simmer theme needs a spacer image, this is a 1x1 transparent gif.
You can just copy this from another simmer theme.

Optional image files:

Bar Images
The bar is composed of Bar_L.gif, Bar_R.gif and Bar_M.gif in the middle.
The middle is stretched.  If you need a middle piece that isn't stretched, use:
  Bar_L.gif, Bar_ML.gif, Bar_M.gif, Bar_MR.gif, Bar_R.gif
And then the Bar_ML.gif and Bar_MR.gif will be stretched.  (See the
Craftsman theme for an example of this).

Locked.gif
A lock image for any directories that have .htaccess

Background image
If you want a background image, specify it in the Font file in the $BODY
section, as in the example above.  The $PATH variable will be replaced
with the path to the theme files:

More.gif
When an album page has sub-albums to list, it first shows the 'More.gif'
image.

Next.gif, Prev.gif, Back.gif
For the next and previous arrows and the back button

Icon.gif
Shown at the top left by the parent albums, this is often just the text "Photos"

Border Images
There are many ways to slice up a border, from simple to complex, depending on
the complexity of the border and how much you want to be able to stretch it:

  4 pieces  Uses Bord_L.gif, Bord_R.gif, Bord_T.gif, Bord_B.gif
    (The corners go with the left and right images)
    4 piece borders usually don't stretch well so they don't work well on
    image_pages.  Generally you can cut the corners out of the left and
    right images to make:

  8 pieces  Also includes Bord_TL.gif, Bord_TR.gif, Bord_BL.gif, Bord_BR.gif
    8 piece borders allow you to stretch to handle most sized images

  12 pieces  Also includes Bord_LT.gif, Bord_RT.gif, Bord_LB.gif, Bord_RB.gif
    12 pieces allow stretching of borders that have more complex corners (such
    as Dominatrix6 or Ivy)

  Overlay Borders  Can use transparent images that can be partially
    overlaying your thumbnail.  See below.

Here's how the normal border pieces are laid out:

   12 piece borders
      TL  T  TR          8 piece borders       4 piece borders
      LT     RT            TL  T  TR            TTTTTTT
      L  IMG  R            L  IMG  R            L IMG R
      LB     RB            BL  B  BR            BBBBBBB
      BL  B  BR

Note that every row of images must be the same height, though the
widths do not have to line up.  (i.e., height TL = height T = height TR)
(This is not true about overlay borders!)

Once you've created these files, you can run the simmer_theme tool
(an optional tool download at MarginalHacks.com) and your theme will
then be ready to use!

If you need different borders for the image pages, then use the same
filenames prefixed by 'I' - such as IBord_LT.gif, IBord_RT.gif,...

Overlay borders allow for really fantastic effects with image borders.
Currently there's no support for different overlay borders for images.

For using Overlay borders, create images:
      Over_TL.png   Over_T.png   Over_TR.png
      Over_L.png                 Over_R.png
      Over_BL.png   Over_B.png   Over_BR.png

Then figure out how many pixels of the borders are padding (outside photo)
Then put those values in files: Over_T.pad Over_R.pad Over_B.pad Over_L.pad
See "Themes/FunLand" for a simple example

Multi-lingual Images
If your images have text, you can translate them into other languages
so that albums can be generated in other languages.  For example, you
can create a Dutch "More.gif" image and put it in 'lang/nl/More.gif'
in the theme (nl is the language code for Dutch).
When the user runs album in Dutch (album -lang nl) then the theme
will use the Dutch image if found.  Themes/Blue has a simple example.
The currently "translated" images are:
  More, Back, Next, Prev and Icon

You can create an HTML table that shows the translations immediately
available to themes with -list_html_trans:

% album -list_html_trans > trans.html

Then view trans.html in a browser.  Unfortunately different languages
have different charsets, and an HTML page can only have one.  The
output is in utf-8, but you can edit the "charset=utf-8" to properly
view language characters in different charsets (such as hebrew).

If you need more words translated for themes, let me know, and if you
create any new language images for a theme, please send them to me!

4:   From scratch, Theme API

This is a much heavier job - you need to have a very clear idea of
how you want album to place the images on your page.  It might be
a good idea to start with modifying existing themes first to get
an idea of what most themes do.  Also look at existing themes
for code examples (see suggestions above).

Themes are directories that contain at the minimum an 'album.th' file.
This is the album page theme template.  Often they also contain an 'image.th'
which is the image theme template, and any graphics/css used by the theme.
Album pages contain thumbnails and image pages show full/medium sized images.

The .th files are ePerl, which is perl embedded inside of HTML.  They
end up looking a great deal like the actual album and image HTML themselves.

To write a theme, you'll need to understand the ePerl syntax.  You can
find more information from the actual ePerl tool available at MarginalHacks
(though this tool is not needed to use themes in album).

There are a plethora of support routines available, but often only
a fraction of these are necessary - it may help to look at other themes
to see how they are generally constructed.

Function table:

Required Functions
Meta()                    Must be called in the  section of HTML
Credit()                  Gives credit ('this album created by..')
                          Must be called in the  section of HTML
Body_Tag()                Called inside the actual  tag.

Paths and Options
Option($name)             Get the value of an option/configuration setting
Version()                 Return the album version
Version_Num()             Return the album version as just a number (i.e. "3.14")
Path($type)               Returns path info for $type of:
  album_name                The name of this album
  dir                       Current working album directory
  album_file                Full path to the album index.html
  album_path                The path of parent directories
  theme                     Full path to the theme directory
  img_theme                 Full path to the theme directory from image pages
  page_post_url             The ".html" to add onto image pages
  parent_albums             Array of parent albums (album_path split up)
Image_Page()              1 if we're generating an image page, 0 for album page.
Page_Type()               Either 'image_page' or 'album_page'
Theme_Path()              The filesystem path to the theme files
Theme_URL()               The URL path to the theme files

Header and Footer
isHeader(), pHeader()     Test for and print the header
isFooter(), pFooter()     Same for the footer

Generally you loop through the images and directories using local variables:

  my $image = First('pics');
  while ($image) {
    print Name($image);
    $image = Next($image);
  }

This will print the name of each image.  Our object types are either 'pics'
for images or 'dirs' for the child directories.  Here are the object functions:

Objects (type is either 'pics' (default) or 'dirs')
First($type)             Get the first image or sub-album object.
Last($type)              Last object
Next($obj)               Given an object, return the next object
Next($obj,1)             Same, loop past end to beginning.
Prev($obj), Prev($obj,1)  Similar to Next()

num('pics') or just num() Total number of images in this album
num('dirs')               Total number of children/sub-albums
Also:
num('parent_albums')      Total number of parents leading up to this album.

Object lookup:
get_obj($num, $type, $loop)
                          Finds object by number ('pics' or 'dirs').
                          If $loop is set than the count will wrap around.

Object Properties
Each object (image or child albums) has properties.
Some properties are accessed by a single field:

Get($obj,$field)            Get a single field of an object

Field                     Description
-----                     ----------
type                      What type of object?  Either 'pics' or 'dirs'
is_movie                  Boolean: is this a movie?
name                      Name (cleaned and optionally from captions)
cap                       Image caption
capfile                   Optional caption file
alt                       Alt tag 
num_pics                  [directories only, -dir_thumbs] Num of pics in directory
num_dirs                  [directories only, -dir_thumbs] Num of dirs in directory

Some properties are accessed by a field and subfield.  For example,
each image has information for different sizes:  full, medium and thumb
(though 'medium' is optional).

Get($obj,$size,$field)      Get a property for a given size

Size          Field       Description
----          -----       ----------
$size         x           Width
$size         y           Height
$size         file        Filename (without path)
$size         path        Filename (full path)
$size         filesize    Filesize in bytes
full          tag         The tag (either 'image' or 'embed') - only for 'full'

We also have URL information which is access according to the
page it's coming 'from' and the image/page it's pointing 'to':

Get($obj,'URL',$from,$to)   Get a URL for an object from -> to
Get($obj,'href',$from,$to)  Same but wraps it in an 'href' string.
Get($obj,'link',$from,$to)  Same but wraps the object name inside the href link.

From         To           Description
----         --           ----------
album_page   image        Image_URL from album_page
album_page   thumb        Thumbnail from album_page
image_page   image        Image_URL from image_page
image_page   image_page   This image page from another image page
image_page   image_src    The <img src> URL for the image page
image_page   thumb        Thumbnail from image_page

Directory objects also have:

From         To           Description
----         --           ----------
album_page   dir          URL to the directory from it's parent album page

Parent Albums
Parent_Album($num)        Get a parent album string (including the href)
Parent_Albums()           Return a list of the parent albums strings (including href)
Parent_Album($str)        A join($str) call of Parent_Albums()
Back()                    The URL to go back or up one page.

Images
This_Image                The image object for an image page
Image($img,$type)         The <img> tags for type of medium,full,thumb
Image($num,$type)         Same, but by image number
Name($img)                The clean or captioned name for an image
Caption($img)             The caption for an image

Child Albums
Name($alb)
Caption($img)             The caption for an image

Convenience Routines
Pretty($str,$html,$lines) Pretty formats a name.
    If $html then HTML is allowed (i.e., use 0 for <title> and the like)
    Currently just puts prefix dates in a smaller font (i.e. '2004-12-03.Folder')
    If $lines then multilines are allowed
    Currently just follows dates with a 'br' line break.
New_Row($obj,$cols,$off)  Should we start a new row after this object?
                          Use $off if the first object is offset from 1
Image_Array($src,$x,$y,$also,$alt)
                          Returns an <img> tag given $src, $x,...
Image_Ref($ref,$also,$alt)
                          Like Image_Array, but $ref can be a hash of
                          Image_Arrays keyed by language ('_' is default).
                          album picks the Image_Array by what languages are set.
Border($img,$type,$href,@border)
Border($str,$x,$y,@border)
                          Create the full bordered image.
                          See 'Borders' for more information.


If you're creating a theme from scratch, consider adding support for -slideshow.
The easiest way to do this is to cut/paste the "slideshow" code out of an
existing theme.

5:   Submitting Themes

Have a custom theme?  I'd love to see it, even if it's totally site-specific.

If you have a new theme you'd like to offer the public, feel free to send
it to me and/or a URL where I can see how it looks.  Be sure to set the CREDIT
file properly and let me know if you are donating it to MarginalHacks for
everyone to use or if you want it under a specific license.

6:   Converting v2.0 Themes to v3.0 Themes

album v2.0 introduced a theme interface which has been rewritten.  Most
2.0 themes (especially those that don't use many of the global variables)
will still work, but the interface is deprecated and may disappear in
the near future.

It's not difficult to convert from v2.0 to v3.0 themes.

The v2.0 themes used global variables for many things.  These are now
deprecated  In v3.0 you should keep track of images and directories in
variables and use the 'iterators' that are supplied, for example:

  my $image = First('pics');
  while ($image) {
    print Name($image);
    $image = Next($image);
  }

Will loop through all the images and print their names.
The chart below shows you how to rewrite the old style calls which
used a global variable with the new style which uses a local variable,
but to use these calls you need to rewrite your loops as above.

Here is a conversion chart for helping convert v2.0 themes to v3.0:

# Global vars shouldn't be used
# ALL DEPRECATED - See new local variable loop methods above
$PARENT_ALBUM_CNT             Rewrite with: Parent_Album($num) and Parent_Albums($join)
$CHILD_ALBUM_CNT              Rewrite with: my $dir = First('dirs');  $dir=Next($dir);
$IMAGE_CNT                    Rewrite with: my $img = First('pics');  $pics=Next($pics);
@PARENT_ALBUMS                Can instead use: @{Path('parent_albums')}
@CHILD_ALBUMS, @CHILD_ALBUM_NAMES, @CHILD_ALBUM_URLS, ...

# Old global variable modifiers:
# ALL DEPRECATED - See new local variable loop methods above
Next_Image(), Images_Left(), Image_Cnt(), Image_Prev(), Image_Next()
Set_Image_Prev(), Set_Image_Next(), Set_Image_This()
Next_Child_Album(), Child_Album_Cnt(), Child_Albums_Left()

# Paths and stuff
pAlbum_Name()                 Path('album_name')
Album_Filename()              Path('album_file')
pFile($file)                  print read_file($file)
Get_Opt($option)              Option($option)
Index()                       Option('index')
pParent_Album($str)           print Parent_Album($str)

# Parent Albums
Parent_Albums_Left            Deprecated, see '$PARENT_ALBUM_CNT' above
Parent_Album_Cnt              Deprecated, see '$PARENT_ALBUM_CNT' above
Next_Parent_Album             Deprecated, see '$PARENT_ALBUM_CNT' above
pJoin_Parent_Albums           print Parent_Albums(\@_)

# Images, using variable '$img'
pImage()                      Use $img instead and:
                              print Get($img,'href','image');
                              print Get($img,'thumb') if Get($img,'thumb');
                              print Name($img), "</a>";
pImage_Src()                  print Image($img,'full')
Image_Src()                   Image($img,'full')
pImage_Thumb_Src()            print Image($img,'thumb')
Image_Name()                  Name($img)
Image_Caption()               Caption($img)
pImage_Caption()              print Get($img,'Caption')
Image_Thumb()                 Get($img,'URL','thumb')
Image_Is_Pic()                Get($img,'thumb')
Image_Alt()                   Get($img,'alt')
Image_Filesize()              Get($img,'full','filesize')
Image_Path()                  Get($img,'full','path')
Image_Width()                 Get($img,'medium','x') || Get($img,'full','x')
Image_Height()                Get($img,'medium','y') || Get($img,'full','y')
Image_Filename()              Get($img,'full','file')
Image_Tag()                   Get($img,'full','tag')
Image_URL()                   Get($img,'URL','image')
Image_Page_URL()              Get($img,'URL','image_page','image_page') || Back()

# Child album routines, using variable '$alb'
pChild_Album($nobr)           print Get($alb,'href','dir');
                              my $name = Name($alb);
                              $name =~ s/<br>//g if $nobr;
                              print $name,"</a>";
Child_Album_Caption()         Caption($alb,'dirs')
pChild_Album_Caption()        print Child_Album_Caption($alb)
Child_Album_URL()             Get($alb,'URL','dir')
Child_Album_Name()            Name($alb)

# Unchanged
Meta()                        Meta()
Credit()                      Credit()