source: project/wiki/eggref/4/sxml-fu @ 14489

Last change on this file since 14489 was 14489, checked in by sjamaan, 10 years ago

Fix example code

File size: 7.7 KB
Line 
1[[tags: egg]]
2
3== sxml-fu
4
5[[toc:]]
6
7=== Description
8
9A collection of useful SXML procedures and rulesets.
10
11(includes the SXML stuff from the old [[/eggref/3/spiffy-utils|spiffy-utils]],
12which are now no longer specific to spiffy)
13
14=== Author
15
16[[/users/peter-bex|Peter Bex]]
17
18=== Requirements
19
20Requires the [[sxml-transforms]] and [[uri-common]] eggs.
21
22=== Documentation
23
24sxml-fu consists of several modules, which are documented below.
25
26=== sxml-pagination
27
28Pagination can performed by a combination of parameters,
29functions and sxml tag-rules.  The collection of these rules
30is available as {{pagination-rules}}. Using these
31rules requires threading the result through
32{{shortcut-rules}} or rules with similar names and arity.
33When trying to get a big picture of how these work together,
34take a look at the examples listed at the end of this document.
35
36==== Parameters
37
38These parameters can be utilised to get multiple pages on one HTML
39page (by calling {{pre-post-order}} more than once) or getting
40different defaults.
41
42<parameter>(base-uri [uri-reference])</parameter>
43
44This is the base URI to use for the pagination links. It must be an
45[[uri-common]] object.
46
47<parameter>(page-size [number])</parameter>
48
49The size of a page/the number of entries on a page.
50Defaults to: 20
51
52<parameter>(page-var [symbol])</parameter>
53
54The GET variable to use for this page.
55Defaults to: {{'page}}
56
57==== Tags
58
59   Tag: (paginate-list sxml-code list)
60   
61By far the easiest pagination tag to use.  This just paginates all
62entries in the list using the sxml-code as template.  See also
63{{entries}}.  The example should be clarifying.
64
65   Tag: (paginate sxml-code entries entries-length)
66
67Basic pagination.  This automates only the templating, it requires you
68to pass it '''only''' the entries on the current page and the total
69number of entries on all pages.  See also {{entries}}.  This tag is
70especially useful if generating every entry on every call is too
71expensive (ie, grabbing entries from a database).  Use the functions
72{{first-entry}} and {{last-entry}} to get the current entries to use.
73
74   Tag: (entries sxml-code)
75
76This tag delimits the part of the template that is to be repeated for
77every entry that is displayed on the page.
78
79===== Tags below 'entries'
80
81These tags are available only as descendents of an
82{{entries}} tag.
83
84   Tag: (pagination-links)
85
86Shows links to the first, previous, next, last and all page numbers in between.
87
88   Tag: (current-page)
89
90The number of the page that's currently being viewed.  See also the
91procedure {{determine-page}}.
92
93   Tag: (first-entry)
94
95The first entry on the page that's currently being viewed.
96See also the procedure {{first-entry}}.
97
98   Tag: (last-entry)
99
100The last entry on the page that's currently being viewed.
101See also the procedure {{last-entry}}.
102
103   Tag: (page-count)
104
105The total number of pages required to fit all the entries on.
106See also the procedure {{page-count}}.
107
108==== Procedures
109
110All these procedures assume the parameters listed above are correctly
111set (ie, match the value when calling {{pre-post-order}} on the tags.
112
113<procedure>(determine-page num-entries)</procedure>
114
115Determine the number of the page currently being viewed.  The total
116number of entries on all pages is required.
117
118<procedure>(page-count num-entries)</procedure>
119
120Returns the total number of pages.  The total number of entries on all
121pages is required.
122
123<procedure>(first-entry num-entries)</procedure>
124
125Returns the position of the first entry on the page currently being
126viewed.
127
128<procedure>(last-entry num-entries)</procedure>
129
130Returns the position of the last entry on the page currently being viewed.
131
132==== Example
133
134<enscript highlight=scheme>
135;; A quick example of how to use pagination-rules
136(use sxml-pagination sxml-shortcuts sxml-transforms doctype srfi-1)
137
138(define my-conversion-rules
139  `((doctype . ,(lambda (doctype) doctype:xhtml-1.0-strict))
140    ,@universal-conversion-rules))
141
142(define content
143  `((doctype)
144    (html
145     (head
146      (title "Showing page" (current-page) " of " (page-count)))
147     (body
148      (paginate-list
149       (div (@ (class "paginated-stuff"))
150            (p "Click on a number to flip to the corresponding page:")
151            (pagination-links)
152            (p "Below we see something that is shown only once per page "
153               "(the UL), which has subentries that are shown many times "
154               "per page, ie the entries on the page (the LIs):")
155            (ul
156             (entries
157              (li (entry))))
158            (p "As we can see, every part of the page that has to be "
159               "for every entry is enclosed by the (entries) 'tag'."
160               "We can also show the same entries twice or more:")
161            (ol
162             (entries
163              (li (entry))))
164            (p "Showing entry" (first-entry) " through " (last-entry) " on "
165               "page " (current-page) " of " (page-count) "."))
166       ,(iota 109))
167      (p "We are showing entry " ,(first-entry 109) " through "
168         ,(last-entry 109) ".")
169      (p "Note that it is necessary to pass the total number of entries "
170         "to every pagination function, but not the actual tags within "
171         "(pagination).  This is because the paginator has no way of "
172         "determining this outside of the (paginate-list) 'tag'.")))))
173
174(define (output-html content . rules)
175  (SRV:send-reply (fold (lambda (ruleset content)
176                          (pre-post-order content ruleset)) content rules)))
177
178(parameterize ((base-uri (request-uri (current-request))))
179   (output-html content pagination-rules shortcut-rules my-conversion-rules))
180</enscript>
181
182=== sxml-shortcuts
183
184
185<constant>shortcut-rules</constant>
186
187These are some convenience functions that simplify common tags,
188described below.
189
190   Tag: (url href . code)
191
192Short for {{`(a (@ (href ,href)) ,code...)}}.
193
194   Tag: (pic src alt [title] . rest)
195
196Short for {{`(img (@ (src ,src) (alt ,alt) (title ,title) ,@rest))}}.
197
198If {{title}} is not provided, it is equal to {{alt}}.
199
200   Tag: (movie src title . rest)
201
202Short for:
203
204<enscript highlight=scheme>
205`(object (@ (type "video/quicktime"))
206   (param (@ (name "src") (value ,src)))
207   (param (@ (name "controller") (value "true")))
208   ,@rest
209   (url ,src ,title))
210</enscript>
211
212That is, it shows the movie pointed to by {{src}} embedded in the
213browser.  If the browser does not support it, an url with the
214description {{title}} is provided.
215
216
217=== Changelog
218
219* 0.1 Initial release (port of [[/eggref/3/spiffy-utils|spiffy-utils]])
220
221=== License
222
223  Copyright (c) 2004-2008, Peter Bex
224  All rights reserved.
225 
226  Redistribution and use in source and binary forms, with or without
227  modification, are permitted provided that the following conditions are
228  met:
229 
230  Redistributions of source code must retain the above copyright
231  notice, this list of conditions and the following disclaimer.
232 
233  Redistributions in binary form must reproduce the above copyright
234  notice, this list of conditions and the following disclaimer in the
235  documentation and/or other materials provided with the distribution.
236 
237  Neither the name of the author nor the names of its contributors may
238  be used to endorse or promote products derived from this software
239  without specific prior written permission.
240 
241  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
242  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
243  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
244  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
245  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
246  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
247  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
248  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
249  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
250  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
251  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
252  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.