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-informal

Description

This egg provides an SXML ruleset for facilitating the creation of HTML forms.

informal-rules

[constant] informal-rules

This constant contains the ruleset which is to be used with sxml-transforms. See below for an explanation of the provided rules. This is the only identifier exported by sxml-informal.

Grouping Rules

[syntax] (informal options . body)

This is the wrapping rule for all further rules. It creates a form tag according to the alist options. The available keys are:

prefix: a string which will be prepended to all of this form's input elements' name and id attributes.
@: the SXML attribute list for the resulting form tag, passed verbatim; use this to set the form's action etc.

Alternatively options may be an immediate attribute list if no futher configuration is needed.

The body should contain the form's input elements (see Input Element Rules).

[syntax] (fields #!optional legend . elements)

This rule should be used inside an informal's body to group a set of input elements. The resulting SXML will wrap them in a fieldset element, possibly with a legend. The elements are then wrapped in an ol elements, thus elements must be a list of li elements. This is sensible because all sxml-informal's input element rules transform into input elements li wrapped elements.

Input Element Rules

All following rules transform to differnt kinds of input elements wrapped in an <li> element. Its class attribute is set to the input's type (e.g. "string" or "text") and name. Further classes may be set depending on certain conditions (see below).

All input element rules accept a name argument which is used to for the element's name and id attributes, possibly prefixed by the surrounding informal rule's prefix name. Additionally, at least the following keyword arguments are accepted:

label: The text which is used for the label element attached to the respective input element. When this is #f, no label element is generated. Default value: #f
value: The input element's current value. If this is #f, no value is set. Default: #f
error: A string or a list of strings of errors to be attached to the respective element. If only one error is passed, it is wrapped in a <span class="error">. Two or more errors are wrapped in an <ul class="errors"> and each error is then made an <li> of that list. All non-false values will attach the class "invalid" to the parent <li>. When this is #f, this argument doesn't have any effect. Default: {{#f}

The basic expansion of input elements is thus something like this:

    (li (@ (class "<type> <name> <invalid>"))
       <label>
       <input>
       <errors>)

Some elements' label follows the input element rather than preceding it (e.g. for checkboxes and radio buttons).

[procedure] (string name #!key value label error)
[procedure] (password name #!key value label error)

These rules translate into input elements of the respective types text or password wrapped in the element markup described under Input Element Rules. The input element expansion is

   (input (@ (type <type>) (id <name>) (name <name>) (value <value>)))

[procedure] (checkbox #!key value label error checked)

This rule expands into a checkbox input element, followed by its label, wrapped in the element markup described under Input Element Rules. It accepts the following additional keyword arguments:

checked: determines whether the checkbox is checked. Default: #f

The input element expansion is

   (input (@ (type "checkbox") (id <name>) (name <name>) (value <value>) [(checked "checked")]))

[procedure] (radio #!key value suffix label error checked)

This rule expands into a radio button element, followed by its label, wrapped in the element markup described under Input Element Rules. It accepts the following additional keyword arguments:

checked: determines whether the checkbox is checked. Default: #f
suffix: the suffix for this input's id attribute. Default: (conc "-" value)

The input element expansion is

   (input (@ (type "radio") (id <id>) (name <name>) (value <value>) [(checked "checked")]))

[procedure] (hidden name value)

This rule expands into a hidden field element without any wrapping like this:

   (input (@ (type "hidden") (id <id>) (name <name>) (value <value>)))

[procedure] (text name #!key value label error)

This rule translates into a textarea element wrapped in the element markup described under Input Element Rules. The textarea element expansion is

   (textarea (@ (id <name>) (name <name>)) <value>)

[procedure] (select name #!key options value label error)

This rule translates into a select element wrapped in the element markup described under Input Element Rules. It accepts the following additional keyword arguments:

options: an alist ((<value> <text>) ...) which is turned into the select's option elements.
value: is used to determine on which option element the selected attribute is set by comparing it to the values given in options.

The select element expansion is

   (select (@ (id <name>) (name <name>)) 
    [(option (@ (value <value>)) <text>) ...])

[procedure] (submit label #!key name)

This rule translates into a submit input element wrapped in the element markup described under Input Element Rules. The input element expansion is

   (input (@ (type "submit") (id <name>) (name <name>) (value <label>)))

Example

    
(use sxml-transforms sxml-informal)

(pre-post-order* '(informal (@ (action "/postings") (method "POST"))
                            (fields "Posting"
                                    (string "author" label: "Your name")
                                    (string "title" label: "Title")
                                    (text "body" label: "Text"))

                            (fields (submit "Save")
                                    (submit "Publish" name: "publish")))
                 informal-rules)

Result:

    
(form (@ (action "/postings") (method "POST"))
      (fieldset (legend "Posting")
                (ol (li (@ (class "string author")) 
                        (label (@ (for "author")) "Your name")
                        (input (@ (type "text") (id "author") (name "author"))))
                    (li (@ (class "string title"))
                        (label (@ (for "title")) "Title")
                        (input (@ (type "text") (id "title") (name "title"))))
                    (li (@ (class "text body")) 
                        (label (@ (for "body")) "Text")
                        (textarea (@ (id "body") (name "body")) #f))))
      (fieldset (ol (li (@ (class "submit commit"))
                        (input (@ (type "submit") (id "commit") (name "commit") (value "Save"))))
                    (li (@ (class "submit publish")) 
                        (input (@ (type "submit") (id "publish") (name "publish") (value "Publish")))))))