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

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

Describe that href/src can now be uri-common objects

File size: 7.9 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) xhtml-1.0-strict))
140    ,@universal-conversion-rules))
141
142(define content
143  (lambda ()
144  `((doctype)
145    (html
146     (head
147      (title "Showing page" ,(determine-page 109) " of " ,(page-count 109)))
148     (body
149      (paginate-list
150       (div (@ (class "paginated-stuff"))
151            (p "Click on a number to flip to the corresponding page:")
152            (pagination-links)
153            (p "Below we see something that is shown only once per page "
154               "(the UL), which has subentries that are shown many times "
155               "per page, ie the entries on the page (the LIs):")
156            (ul
157             (entries
158              (li (entry))))
159            (p "As we can see, every part of the page that has to be "
160               "for every entry is enclosed by the (entries) 'tag'."
161               "We can also show the same entries twice or more:")
162            (ol
163             (entries
164              (li (entry))))
165            (p "Showing entry" (first-entry) " through " (last-entry) " on "
166               "page " (current-page) " of " (page-count) "."))
167       ,(iota 109))
168      (p "We are showing entry " ,(first-entry 109) " through "
169         ,(last-entry 109) ".")
170      (p "Note that it is necessary to pass the total number of entries "
171         "to every pagination function, but not the actual tags within "
172         "(pagination).  This is because the paginator has no way of "
173         "determining this outside of the (paginate-list) 'tag'."))))))
174
175(define (output-html content . rules)
176  (SRV:send-reply (fold (lambda (ruleset content)
177                          (pre-post-order content ruleset)) content rules)))
178
179(parameterize ((base-uri (request-uri (current-request))))
180   (output-html (content) pagination-rules shortcut-rules my-conversion-rules))
181</enscript>
182
183=== sxml-shortcuts
184
185
186<constant>shortcut-rules</constant>
187
188These are some convenience functions that simplify common tags,
189described below.
190
191   Tag: (url href . code)
192
193Short for {{`(a (@ (href ,href)) ,code...)}}.
194{{href}} can be a string or a [[uri-common]] object.
195
196   Tag: (pic src alt [title] . rest)
197
198Short for {{`(img (@ (src ,src) (alt ,alt) (title ,title) ,@rest))}}.
199{{src}} can be a string or a [[uri-common]] object.
200
201If {{title}} is not provided, it is equal to {{alt}}.
202
203   Tag: (movie src title . rest)
204
205Short for:
206
207<enscript highlight=scheme>
208`(object (@ (type "video/quicktime"))
209   (param (@ (name "src") (value ,src)))
210   (param (@ (name "controller") (value "true")))
211   ,@rest
212   (url ,src ,title))
213</enscript>
214
215That is, it shows the movie pointed to by {{src}} embedded in the
216browser.  If the browser does not support it, an url with the
217description {{title}} is provided.
218
219{{src}} can be a string or a [[uri-common]] object.
220
221=== Changelog
222
223* 0.1 Initial release (port of [[/eggref/3/spiffy-utils|spiffy-utils]])
224
225=== License
226
227  Copyright (c) 2004-2008, Peter Bex
228  All rights reserved.
229 
230  Redistribution and use in source and binary forms, with or without
231  modification, are permitted provided that the following conditions are
232  met:
233 
234  Redistributions of source code must retain the above copyright
235  notice, this list of conditions and the following disclaimer.
236 
237  Redistributions in binary form must reproduce the above copyright
238  notice, this list of conditions and the following disclaimer in the
239  documentation and/or other materials provided with the distribution.
240 
241  Neither the name of the author nor the names of its contributors may
242  be used to endorse or promote products derived from this software
243  without specific prior written permission.
244 
245  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
246  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
247  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
248  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
249  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
250  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
251  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
252  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
253  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
254  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
255  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
256  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.