|
A l b u m S e v e n - - C r e a t i n g T h e m e s |
|
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. 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 Font and CREDIT file, then simmer_theme will create the *.th files to make the theme complete. Files: Font The font file sets the fonts used by the theme. This will probably be replaced with CSS in the very near future. 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. Otherwise the two lines are: 1) A short description of the theme 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 files: Bar Images The bar is composed of Bar_L.gif, Bar_R.gif and Bar_M.gif in the middle (stretched). 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) Here's how the 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 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! 4: From scratch, Theme API 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 head section of HTML Credit() Gives credit ('this album created by..') Must be called in the body section of HTML Paths and Options Option($name) Get the value of an option/configuration setting 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() New_Row($obj,$cols,$off) Should we start a new row after this object? Use $off if the first object is offset from 1 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. 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 Image_Array($src,$x,$y,$also,$alt) Returns an <img> tag given $src, $x,... Border($img,$type,$href,@border) Border($str,$x,$y,@border) Create the full bordered image. See 'Borders' for 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 had 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()
|