source: project/wiki/eggref/4/phoghorn @ 16951

[[tags: egg]]

== phoghorn

[[toc:]]

=== Description

A thumbnail gallery library for [[spiffy]].

=== Author

[[/users/peter-bex|Peter Bex]]

=== Requirements

Requires [[spiffy]], [[sxml-transforms]], [[uri-common]], [[imlib2]] and [[epeg]].
You will also need to install [[sxml-fu]] to make use of it.

=== Documentation

Phoghorn is a web-based image gallery with built-in automatic thumbnail generator for [[spiffy]] the webserver.

Its features are:

* Easy to use (just drop a bunch of files in a directory underneath the designated photos dir)
* Configurable
* Does not require a database
* Uses CSS for styling, so its look is easily changed
* Leverages [[imlib2]] for maximum image file type support and [[epeg]] for extra-speedy JPEG handling.
* Built with SXML for clean and semantic source markup, with all benefits of a functional programming style.

=== Usage

By default, phoghorn assumes there is a directory called {{galleries}}
in the directory from which you call its functions (ie, the same
directory in which you placed {{index.ws}} or {{index.ssp}}). It will
create thumbnails on-the-fly when there aren't any yet, and only for
those pictures on the page that is currently being viewed.  By
default, these will be placed in the {{thumbs}} directory under the
gallery's directory.

In the main page (save this as {{index.ssp}}):

<enscript highlight=scheme>
(use phoghorn sxml-transforms uri-common sxml-pagination sxml-shortcuts)

(define content
  `((html
     (head (title "Showing gallery: " ,(current-gallery)))
     (body
      (phoghorn-gallery)))))

(define (output-html content . rules)
  (SRV:send-reply (fold (lambda (ruleset content)
                          (pre-post-order content ruleset)) content rules)))

;; We want bigger pages
(parameterize ((page-size 40)
               (base-uri (request-uri (current-request))))
  (output-html content phoghorn-rules pagination-rules shortcut-rules universal-conversion-rules))
</enscript>

Phoghorn generates output that must be processed by the
{{pagination-rules}} and {{shortcut-rules}} from the [[sxml-fu]] egg,
hence the complicated output statement.

In the zoomed-in page (save this as {{zoomed.ssp}}):

<enscript highlight=scheme>
(use phoghorn sxml-transforms sxml-shortcuts)

(define content
  `((html
     (head (title "Showing photo: " ,(current-entry-filename))
     (body
       (phoghorn-zoomed-entry))))))

(define (output-html content . rules)
  (SRV:send-reply (fold (lambda (ruleset content)
                          (pre-post-order content ruleset)) content rules)))

;; The shortcut-rules and the pagination-rules are mandatory, by the way
(output-html content phoghorn-rules shortcut-rules universal-conversion-rules)
</enscript>

=== Configuration

Phoghorn can be customised to the max.  The following [[http://srfi.schemers.org/srfi-39/|SRFI-39 parameters]] are supported, in addition to the configuration options for [[sxml-fu#pagination|sxml-fu's pagination rules]] (which phoghorn uses internally):

==== Directory and file settings

<parameter>(gallery-dir [directory-name])</parameter>

The directory under which the galleries can be found, relative to the index page.
Defaults to {{"galleries"}}.

<parameter>(gallery-url [url-string])</parameter>

The page that shows gallery listings with thumbnail entries.
Defaults to {{"index.ssp"}}

<parameter>(zoomed-url [url-string])</parameter>

The webpage that serves the zoomed-in views on images.
Defaults to {{"zoomed.ssp"}}

<parameter>(thumb-dir [directory-name])

The name of the directory under which thumnail versions of the images
in the parent directory are stored.
Defaults to {{"thumbs"}}.
                     
==== Variable control

<parameter>(gallery-var [symbol])</parameter>

The name of the GET parameter that contains the gallery the user wishes to view.
Defaults to {{gallery}}.

<parameter>(entry-var [symbol])</parameter>

The name of the GET parameter that contains the entry the user wishes
to view (when zoomed).
Defaults to {{entry}}.

==== Thumbnail generation

<parameter>(max-thumb-dimensions [number])</parameter>

Maximum width ''or'' height of a thumbnail.

The smaller of the two will get scaled by the same factor as the
larger, which will be shrunk into this size. In other words, it
maintains the aspect ratio of the original picture in the thumb.

Defaults to {{100}}.

==== Presentational options

<parameter>(movie-image [url-string])</parameter>

The image file to display when a movie is in the gallery.
Defaults to {{"/pics/movie.jpg"}}.

<parameter>(root-gallery-name [string])</parameter>

The title of the topmost gallery.  All subgalleries have a title that
is equal to the directory name.
Defaults to {{"Galleries"}}.

=== Procedures

You can use these procedures if you want more control over the 
way your gallery is output, ie using it more as a library than
as a complete thumbnail gallery package.

<procedure>(gallery-contents)</procedure>

Get the contents of the currently selected gallery (as determined by
{{gallery-var}}).

Returns two values: The first value is a list of subgalleries in that
gallery, the second value is a list of entries (ie, pictures) in that
gallery.

<procedure>(thumbnail gallery entry)</procedure>

Returns a link to the thumbnail picture of the selected entry under
the selected gallery.

Chooses {{thumbnail/epeg}} or {{thumbnail/imlib2}} based on the entry file.

Side-effects: creates the thumbnail if it does not exist and creates
the thumbs directory as determined by {{thumb-dir}} if necessary.

<procedure>(thumbnail/epeg gallery entry)</procedure>

Epeg-specific version of {{thumbnail}}.
'''Note: the source image must be a jpeg.'''

<procedure>(thumbnail/imlib2 gallery entry)</procedure>

Imlib2-specific version of {{thumbnail}}.

'''Note: the source image must be of a type understood by imlib2.'''

<procedure>(galleries-up-to gallery)</procedure>

Returns a list of all the galleries from the root gallery up to the
specified gallery.

<procedure>(prev-entry entry entries)</procedure>

Return the filename of the previous entry in the {{entries}} list, as
seen from the selected entry.  Returns {{#f}} if this is the first
entry in the list.

<procedure>(next-entry entry entries)</procedure>

Return the filename of the next entry in the {{entries}} list, as seen
from the selected entry.  Returns {{#f}} if this is the last entry in
the list.

=== Tags

This section describes the SXML tags that are available when 
you use {{phoghorn-rules}}.  You can override the default phoghorn
transformation rules for these tags, or generate these tags
yourself and have phoghorn transform them for you.

   [tag] (phoghorn-gallery)

Output the current gallery, including links to its subgalleries (if
any) and entry thumbnails (if any).  Also shows breadcrumb links.

   [tag] (gallery-entries entries)

Shows an unordered list of the paginated {{entries}}, headed by a
pagination list.

   [tag] (gallery-list galleries)

Shows an unordered list of (sub) galleries.

   [tag] (gallery-link gallery)

Generates a link to the given gallery.  If {{gallery}} is {{#f}} , a
link to the root gallery with {{(root-gallery-name)}} " as the link
title is generated.

   [tag] (gallery-entry gallery entry)

Generates a link to the zoomed version of {{entry}} with the
(generated if necessary) thumbnail.

   [tag] (zoomed-url gallery entry)

Generates a link to {{zoomed-url}} with the gallery and entry as
parameters. (using {{link-to}}).

   [tag] (phoghorn-breadcrumbs gallery)

Generate [[http://developer.yahoo.com/ypatterns/pattern.php?pattern=breadcrumbs|breadcrumb]] links from the root gallery up to the selected gallery.

   [tag] (phoghorn-zoomed-entry)

Show the currently zoomed entry picture full-size.  Includes
navigation to the next and previous entry and breadcrumbs.

   [tag] (entry-navigation)

Generate navigation to the next and previous entry link in the current
gallery, relative to the currently selected entry as determined from
{{gallery-var}} and {{entry-var}}.

   [tag] (zoomed-picture gallery entry)

The zoomed entry picture in the selected gallery.

=== Changelog

* 2.3 Port to Chicken 4 and Spiffy 4.
* 2.2 Update to new version of Spiffy - (current-workdir) now means something else so phoghorn >= 2.2 _does not work_ with Spiffy < 3.9
* 2.1 Update to new version of spiffy-utils.
* 2.0 Complete rewrite in SXML.
* 1.2 Update to latest versions of epeg and imlib2.
* 1.1.1 Changed .setup script to reflect new distribution of syntax-case.
* 1.1 Fix small bug (a let statement was closed a little too early.
* 1.0 initial release.

=== License

  Copyright (c) 2005-2009, Peter Bex
  All rights reserved.
  
  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions are
  met:
  
  Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.
  
  Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.
  
  Neither the name of the author nor the names of its contributors may
  be used to endorse or promote products derived from this software
  without specific prior written permission.
  
  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  OF THE POSSIBILITY OF SUCH DAMAGE.