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

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

Add eggref documentation for phoghorn

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