A collection of useful SXML procedures and rulesets.
(includes the SXML stuff from the old spiffy-utils, which are now no longer specific to spiffy)
sxml-fu consists of several modules, which are documented below.
This module contains useful procedures that allow you to use the other modules more easily.
- output-xml tree rulesetsprocedure
Output the sxml in tree to the current output port, after folding over the rulesets using sxml-fold-rules.
- sxml-fold-rules tree rulesetsprocedure
Fold over the list of rulesets by calling pre-post-order on each, in turn, starting with the tree input. The final output of pre-post-order on the last ruleset is returned.
- normal->starred-transformation-rules rulesprocedure
Convert traditional sxml transformation rules (where handlers accept a fixed number of arguments corresponding to the element and its child nodes) to their "starred" equivalents (where handlers accept two arguments; the element and a list of its child nodes).
See the sxml-transforms egg manual for more information about "starred rules".
This will not make these handlers magically accept huge nodes. This is merely for convenience when you want to convert some legacy rules to fit into an application based on starred rules.
- starred->normal-transformation-rules rulesprocedure
Convert "starred" sxml transformation rules (where handlers accept two arguments; the element and a list of its child nodes) to their traditional equivalents (where handlers accept a fixed number of arguments corresponding to the element and its child nodes).
This procedure is useful for integrating new rules into legacy applications. Note that after applying this the handlers will have limited node size accepted.
Pagination can be performed by a combination of parameters, functions and sxml tag-rules. The collection of these rules is available as pagination-rules or pagination-rules* for the "starred" version. Using these rules requires threading the result through shortcut-rules/shortcut-rules* or rules that expect the same elements and structure. When trying to get a big picture of how these work together, take a look at the examples listed at the end of this document.
These parameters can be utilised to get multiple pages on one HTML page (by calling pre-post-order more than once) or getting different defaults.
- base-uri #!optional uri-referenceparameter
This is the base URI to use for the pagination links. It must be an uri-common object.
- page-size #!optional numberparameter
The size of a page/the number of entries on a page. Defaults to: 20
- page-var #!optional symbolparameter
The GET variable to use for this page. Defaults to: 'page
Tag: (paginate-list sxml-code list)
By far the easiest pagination tag to use. This just paginates all entries in the list using the sxml-code as template. See also entries. The example should be clarifying.
Tag: (paginate sxml-code entries entries-length)
Basic pagination. This automates only the templating, it requires you to pass it only the entries on the current page and the total number of entries on all pages. See also entries. This tag is especially useful if generating every entry on every call is too expensive (ie, grabbing entries from a database). Use the functions first-entry and last-entry to get the current entries to use.
Tag: (entries sxml-code)
This tag delimits the part of the template that is to be repeated for every entry that is displayed on the page.
These tags are available only as descendents of an entries tag.
Shows links to the first, previous, next, last and all page numbers in between.
The number of the page that's currently being viewed. See also the procedure determine-page.
The first entry on the page that's currently being viewed. See also the procedure first-entry.
The last entry on the page that's currently being viewed. See also the procedure last-entry.
The total number of pages required to fit all the entries on. See also the procedure page-count.
All these procedures assume the parameters listed above are correctly set (ie, match the value when calling pre-post-order on the tags.
- determine-page num-entriesprocedure
Determine the number of the page currently being viewed. The total number of entries on all pages is required.
- page-count num-entriesprocedure
Returns the total number of pages. The total number of entries on all pages is required.
- first-entry num-entriesprocedure
Returns the position of the first entry on the page currently being viewed.
- last-entry num-entriesprocedure
Returns the position of the last entry on the page currently being viewed.
;; A quick example of how to use pagination-rules (use sxml-pagination sxml-shortcuts sxml-transforms doctype srfi-1) (define my-conversion-rules `((doctype . ,(lambda (doctype) xhtml-1.0-strict)) ,@universal-conversion-rules)) (define content (lambda () `((doctype) (html (head (title "Showing page" ,(determine-page 109) " of " ,(page-count 109))) (body (paginate-list (div (@ (class "paginated-stuff")) (p "Click on a number to flip to the corresponding page:") (pagination-links) (p "Below we see something that is shown only once per page " "(the UL), which has subentries that are shown many times " "per page, ie the entries on the page (the LIs):") (ul (entries (li (entry)))) (p "As we can see, every part of the page that has to be " "for every entry is enclosed by the (entries) 'tag'." "We can also show the same entries twice or more:") (ol (entries (li (entry)))) (p "Showing entry" (first-entry) " through " (last-entry) " on " "page " (current-page) " of " (page-count) ".")) ,(iota 109)) (p "We are showing entry " ,(first-entry 109) " through " ,(last-entry 109) ".") (p "Note that it is necessary to pass the total number of entries " "to every pagination function, but not the actual tags within " "(pagination). This is because the paginator has no way of " "determining this outside of the (paginate-list) 'tag'.")))))) (parameterize ((base-uri (request-uri (current-request)))) (output-xml (content) (list pagination-rules shortcut-rules my-conversion-rules)))
These are some convenience functions that simplify common tags, described below.
Tag: (url href . code)
Short for `(a (@ (href ,href)) ,code...). href can be a string or a uri-common object.
Tag: (pic src alt [title] . rest)
Short for `(img (@ (src ,src) (alt ,alt) (title ,title) ,@rest)). src can be a string or a uri-common object.
If title is not provided, it is equal to alt.
Tag: (movie src title . rest)
`(object (@ (type "video/quicktime")) (param (@ (name "src") (value ,src))) (param (@ (name "controller") (value "true"))) ,@rest (url ,src ,title))
That is, it shows the movie pointed to by src embedded in the browser. If the browser does not support it, an url with the description title is provided.
src can be a string or a uri-common object.
- 0.3 Add conversion procedures between starred and nonstarred forms and add output rules for starred rules. Convert shortcut and pagination rules to starred forms.
- 0.2 Add procedures in sxml-fu module
- 0.1 Initial release (port of spiffy-utils)
Copyright (c) 2004-2010, Peter Bex All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.