You are looking at historical revision 14442 of this page. It may differ significantly from its current revision.

sxml-fu

Description

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)

Author

Peter Bex

Requirements

Requires the sxml-transforms and uri-common eggs.

Documentation

sxml-fu consists of several modules, which are documented below.

sxml-pagination

Pagination can performed by a combination of parameters, functions and sxml tag-rules. The collection of these rules is available as pagination-rules. Using these rules requires threading the result through shortcut-rules or rules with similar names and arity. 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.

Parameters

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.

[parameter] (base-uri [uri-reference])

This is the base URI to use for the pagination links. It must be an uri-common object.

[parameter] (page-size [number])

The size of a page/the number of entries on a page. Defaults to: 20

[parameter] (page-var [symbol])

The GET variable to use for this page. Defaults to: 'page

Tags

  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.

Tags below 'entries'

These tags are available only as descendents of an entries tag.

  Tag: (pagination-links)

Shows links to the first, previous, next, last and all page numbers in between.

  Tag: (current-page)

The number of the page that's currently being viewed. See also the procedure current-page.

  Tag: (first-entry)

The first entry on the page that's currently being viewed. See also the procedure first-entry.

  Tag: (last-entry)

The last entry on the page that's currently being viewed. See also the procedure last-entry.

  Tag: (page-count)

The total number of pages required to fit all the entries on. See also the procedure page-count.

Procedures

All these procedures assume the parameters listed above are correctly set (ie, match the value when calling pre-post-order on the tags.

[procedure] (current-page num-entries)

Returns the number of the page currently being viewed. The total number of entries on all pages is required.

[procedure] (page-count num-entries)

Returns the total number of pages. The total number of entries on all pages is required.

[procedure] (first-entry num-entries)

Returns the position of the first entry on the page currently being viewed.

[procedure] (last-entry num-entries)

Returns the position of the last entry on the page currently being viewed.

Example

;; A quick example of how to use pagination-rules
(use sxml-fu sxml-transforms doctype srfi-1)

(define my-conversion-rules
  `((doctype . ,(lambda (doctype) doctype:xhtml-1.0-strict))
    ,@universal-conversion-rules))

(define content
  `((doctype)
    (html
     (head
      (title "Showing page" ,(current-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'.")))))

(define (output-html content . rules)
  (SRV:send-reply (fold (lambda (ruleset content)
			  (pre-post-order content ruleset)) content rules)))

(parameterize ((base-uri (request-uri (current-request))))
   (output-html content pagination-rules shortcut-rules my-conversion-rules))

sxml-shortcuts

[constant] shortcut-rules

These are some convenience functions that simplify common tags, described below.

  Tag: (url href . code)

Short for `(a (@ (href ,href)) ,code...).

  Tag: (pic src alt [title] . rest)

Short for `(img (@ (src ,src) (alt ,alt) (title ,title) ,@rest)).

If title is not provided, it is equal to alt.

  Tag: (movie src title . rest)

Short for:

`(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.

Changelog

License

 Copyright (c) 2004-2008, 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.