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

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

Update copyright year

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