chickadee » sxml-fu

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

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, matchable and uri-common eggs.

Documentation

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

sxml-fu

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.

output-xml* tree rulesetsprocedure

Same as output-xml, for starred 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.

sxml-fold-rules* tree rulesetsprocedure

Same as sxml-fold-rules, for starred rules.

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.

sxml-pagination

pagination-rulesconstant
pagination-rules*constant

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.

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.

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

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 determine-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.

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.

Example

;; 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)))

sxml-shortcuts

shortcut-rulesconstant
shortcut-rules*constant

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)

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.

src can be a string or a uri-common object.

Changelog

License

 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.

Contents »