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

Last change on this file since 16951 was 16951, checked in by sjamaan, 11 years ago

Fix all links to 'mail.nongnu.org' so they point to the new 'lists.nongnu.org', instead

File size: 9.9 KB
Line 
1[[tags: egg]]
2
3== phoghorn
4
5[[toc:]]
6
7=== Description
8
9A thumbnail gallery library for [[spiffy]].
10
11=== Author
12
13[[/users/peter-bex|Peter Bex]]
14
15=== Requirements
16
17Requires [[spiffy]], [[sxml-transforms]], [[uri-common]], [[imlib2]] and [[epeg]].
18You will also need to install [[sxml-fu]] to make use of it.
19
20=== Documentation
21
22Phoghorn is a web-based image gallery with built-in automatic thumbnail generator for [[spiffy]] the webserver.
23
24Its features are:
25
26* Easy to use (just drop a bunch of files in a directory underneath the designated photos dir)
27* Configurable
28* Does not require a database
29* Uses CSS for styling, so its look is easily changed
30* Leverages [[imlib2]] for maximum image file type support and [[epeg]] for extra-speedy JPEG handling.
31* Built with SXML for clean and semantic source markup, with all benefits of a functional programming style.
32
33=== Usage
34
35By default, phoghorn assumes there is a directory called {{galleries}}
36in the directory from which you call its functions (ie, the same
37directory in which you placed {{index.ws}} or {{index.ssp}}). It will
38create thumbnails on-the-fly when there aren't any yet, and only for
39those pictures on the page that is currently being viewed.  By
40default, these will be placed in the {{thumbs}} directory under the
41gallery's directory.
42
43In the main page (save this as {{index.ssp}}):
44
45<enscript highlight=scheme>
46(use phoghorn sxml-transforms uri-common sxml-pagination sxml-shortcuts)
47
48(define content
49  `((html
50     (head (title "Showing gallery: " ,(current-gallery)))
51     (body
52      (phoghorn-gallery)))))
53
54(define (output-html content . rules)
55  (SRV:send-reply (fold (lambda (ruleset content)
56                          (pre-post-order content ruleset)) content rules)))
57
58;; We want bigger pages
59(parameterize ((page-size 40)
60               (base-uri (request-uri (current-request))))
61  (output-html content phoghorn-rules pagination-rules shortcut-rules universal-conversion-rules))
62</enscript>
63
64Phoghorn generates output that must be processed by the
65{{pagination-rules}} and {{shortcut-rules}} from the [[sxml-fu]] egg,
66hence the complicated output statement.
67
68In the zoomed-in page (save this as {{zoomed.ssp}}):
69
70<enscript highlight=scheme>
71(use phoghorn sxml-transforms sxml-shortcuts)
72
73(define content
74  `((html
75     (head (title "Showing photo: " ,(current-entry-filename))
76     (body
77       (phoghorn-zoomed-entry))))))
78
79(define (output-html content . rules)
80  (SRV:send-reply (fold (lambda (ruleset content)
81                          (pre-post-order content ruleset)) content rules)))
82
83;; The shortcut-rules and the pagination-rules are mandatory, by the way
84(output-html content phoghorn-rules shortcut-rules universal-conversion-rules)
85</enscript>
86
87=== Configuration
88
89Phoghorn 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):
90
91==== Directory and file settings
92
93<parameter>(gallery-dir [directory-name])</parameter>
94
95The directory under which the galleries can be found, relative to the index page.
96Defaults to {{"galleries"}}.
97
98<parameter>(gallery-url [url-string])</parameter>
99
100The page that shows gallery listings with thumbnail entries.
101Defaults to {{"index.ssp"}}
102
103<parameter>(zoomed-url [url-string])</parameter>
104
105The webpage that serves the zoomed-in views on images.
106Defaults to {{"zoomed.ssp"}}
107
108<parameter>(thumb-dir [directory-name])
109
110The name of the directory under which thumnail versions of the images
111in the parent directory are stored.
112Defaults to {{"thumbs"}}.
113                     
114==== Variable control
115
116<parameter>(gallery-var [symbol])</parameter>
117
118The name of the GET parameter that contains the gallery the user wishes to view.
119Defaults to {{gallery}}.
120
121<parameter>(entry-var [symbol])</parameter>
122
123The name of the GET parameter that contains the entry the user wishes
124to view (when zoomed).
125Defaults to {{entry}}.
126
127==== Thumbnail generation
128
129<parameter>(max-thumb-dimensions [number])</parameter>
130
131Maximum width ''or'' height of a thumbnail.
132
133The smaller of the two will get scaled by the same factor as the
134larger, which will be shrunk into this size. In other words, it
135maintains the aspect ratio of the original picture in the thumb.
136
137Defaults to {{100}}.
138
139==== Presentational options
140
141<parameter>(movie-image [url-string])</parameter>
142
143The image file to display when a movie is in the gallery.
144Defaults to {{"/pics/movie.jpg"}}.
145
146<parameter>(root-gallery-name [string])</parameter>
147
148The title of the topmost gallery.  All subgalleries have a title that
149is equal to the directory name.
150Defaults to {{"Galleries"}}.
151
152=== Procedures
153
154You can use these procedures if you want more control over the
155way your gallery is output, ie using it more as a library than
156as a complete thumbnail gallery package.
157
158<procedure>(gallery-contents)</procedure>
159
160Get the contents of the currently selected gallery (as determined by
161{{gallery-var}}).
162
163Returns two values: The first value is a list of subgalleries in that
164gallery, the second value is a list of entries (ie, pictures) in that
165gallery.
166
167<procedure>(thumbnail gallery entry)</procedure>
168
169Returns a link to the thumbnail picture of the selected entry under
170the selected gallery.
171
172Chooses {{thumbnail/epeg}} or {{thumbnail/imlib2}} based on the entry file.
173
174Side-effects: creates the thumbnail if it does not exist and creates
175the thumbs directory as determined by {{thumb-dir}} if necessary.
176
177<procedure>(thumbnail/epeg gallery entry)</procedure>
178
179Epeg-specific version of {{thumbnail}}.
180'''Note: the source image must be a jpeg.'''
181
182<procedure>(thumbnail/imlib2 gallery entry)</procedure>
183
184Imlib2-specific version of {{thumbnail}}.
185
186'''Note: the source image must be of a type understood by imlib2.'''
187
188<procedure>(galleries-up-to gallery)</procedure>
189
190Returns a list of all the galleries from the root gallery up to the
191specified gallery.
192
193<procedure>(prev-entry entry entries)</procedure>
194
195Return the filename of the previous entry in the {{entries}} list, as
196seen from the selected entry.  Returns {{#f}} if this is the first
197entry in the list.
198
199<procedure>(next-entry entry entries)</procedure>
200
201Return the filename of the next entry in the {{entries}} list, as seen
202from the selected entry.  Returns {{#f}} if this is the last entry in
203the list.
204
205=== Tags
206
207This section describes the SXML tags that are available when
208you use {{phoghorn-rules}}.  You can override the default phoghorn
209transformation rules for these tags, or generate these tags
210yourself and have phoghorn transform them for you.
211
212   [tag] (phoghorn-gallery)
213
214Output the current gallery, including links to its subgalleries (if
215any) and entry thumbnails (if any).  Also shows breadcrumb links.
216
217   [tag] (gallery-entries entries)
218
219Shows an unordered list of the paginated {{entries}}, headed by a
220pagination list.
221
222   [tag] (gallery-list galleries)
223
224Shows an unordered list of (sub) galleries.
225
226   [tag] (gallery-link gallery)
227
228Generates a link to the given gallery.  If {{gallery}} is {{#f}} , a
229link to the root gallery with {{(root-gallery-name)}} " as the link
230title is generated.
231
232   [tag] (gallery-entry gallery entry)
233
234Generates a link to the zoomed version of {{entry}} with the
235(generated if necessary) thumbnail.
236
237   [tag] (zoomed-url gallery entry)
238
239Generates a link to {{zoomed-url}} with the gallery and entry as
240parameters. (using {{link-to}}).
241
242   [tag] (phoghorn-breadcrumbs gallery)
243
244Generate [[http://developer.yahoo.com/ypatterns/pattern.php?pattern=breadcrumbs|breadcrumb]] links from the root gallery up to the selected gallery.
245
246   [tag] (phoghorn-zoomed-entry)
247
248Show the currently zoomed entry picture full-size.  Includes
249navigation to the next and previous entry and breadcrumbs.
250
251   [tag] (entry-navigation)
252
253Generate navigation to the next and previous entry link in the current
254gallery, relative to the currently selected entry as determined from
255{{gallery-var}} and {{entry-var}}.
256
257   [tag] (zoomed-picture gallery entry)
258
259The zoomed entry picture in the selected gallery.
260
261=== Changelog
262
263* 2.3 Port to Chicken 4 and Spiffy 4.
264* 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
265* 2.1 Update to new version of spiffy-utils.
266* 2.0 Complete rewrite in SXML.
267* 1.2 Update to latest versions of epeg and imlib2.
268* 1.1.1 Changed .setup script to reflect new distribution of syntax-case.
269* 1.1 Fix small bug (a let statement was closed a little too early.
270* 1.0 initial release.
271
272=== License
273
274  Copyright (c) 2005-2009, Peter Bex
275  All rights reserved.
276 
277  Redistribution and use in source and binary forms, with or without
278  modification, are permitted provided that the following conditions are
279  met:
280 
281  Redistributions of source code must retain the above copyright
282  notice, this list of conditions and the following disclaimer.
283 
284  Redistributions in binary form must reproduce the above copyright
285  notice, this list of conditions and the following disclaimer in the
286  documentation and/or other materials provided with the distribution.
287 
288  Neither the name of the author nor the names of its contributors may
289  be used to endorse or promote products derived from this software
290  without specific prior written permission.
291 
292  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
293  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
294  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
295  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
296  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
297  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
298  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
299  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
300  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
301  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
302  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
303  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.