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

Last change on this file since 14495 was 14495, checked in by svnwiki, 10 years ago

Changes applied for C-Keen (153.96.215.206) through svnwiki:

make content a procedure and call it, to have the right values for ,(first-entry).

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) 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
195   Tag: (pic src alt [title] . rest)
196
197Short for {{`(img (@ (src ,src) (alt ,alt) (title ,title) ,@rest))}}.
198
199If {{title}} is not provided, it is equal to {{alt}}.
200
201   Tag: (movie src title . rest)
202
203Short for:
204
205<enscript highlight=scheme>
206`(object (@ (type "video/quicktime"))
207   (param (@ (name "src") (value ,src)))
208   (param (@ (name "controller") (value "true")))
209   ,@rest
210   (url ,src ,title))
211</enscript>
212
213That is, it shows the movie pointed to by {{src}} embedded in the
214browser.  If the browser does not support it, an url with the
215description {{title}} is provided.
216
217
218=== Changelog
219
220* 0.1 Initial release (port of [[/eggref/3/spiffy-utils|spiffy-utils]])
221
222=== License
223
224  Copyright (c) 2004-2008, Peter Bex
225  All rights reserved.
226 
227  Redistribution and use in source and binary forms, with or without
228  modification, are permitted provided that the following conditions are
229  met:
230 
231  Redistributions of source code must retain the above copyright
232  notice, this list of conditions and the following disclaimer.
233 
234  Redistributions in binary form must reproduce the above copyright
235  notice, this list of conditions and the following disclaimer in the
236  documentation and/or other materials provided with the distribution.
237 
238  Neither the name of the author nor the names of its contributors may
239  be used to endorse or promote products derived from this software
240  without specific prior written permission.
241 
242  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
243  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
244  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
245  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
246  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
247  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
248  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
249  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
250  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
251  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
252  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
253  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.