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

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

Document changelog 0.2

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.2 Add procedures in {{sxml-fu}} module
237* 0.1 Initial release (port of [[/eggref/3/spiffy-utils|spiffy-utils]])
238
239=== License
240
241  Copyright (c) 2004-2009, Peter Bex
242  All rights reserved.
243 
244  Redistribution and use in source and binary forms, with or without
245  modification, are permitted provided that the following conditions are
246  met:
247 
248  Redistributions of source code must retain the above copyright
249  notice, this list of conditions and the following disclaimer.
250 
251  Redistributions in binary form must reproduce the above copyright
252  notice, this list of conditions and the following disclaimer in the
253  documentation and/or other materials provided with the distribution.
254 
255  Neither the name of the author nor the names of its contributors may
256  be used to endorse or promote products derived from this software
257  without specific prior written permission.
258 
259  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
260  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
261  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
262  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
263  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
264  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
265  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
266  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
267  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
268  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
269  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
270  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.