((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/sxml-informal" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.")) (section 2 "sxml-informal" (section 3 "Description" (p "This egg provides an SXML ruleset for facilitating the creation of HTML forms.")) (section 3 "Author" (p (int-link "/users/moritz-heidkamp" "Moritz Heidkamp"))) (section 3 "informal-rules" (def (sig (constant "informal-rules" (id informal-rules))) (p "This constant contains the ruleset which is to be used with " (int-link "sxml-transforms") ". See below for an explanation of the provided rules. This is the only identifier exported by " (tt "sxml-informal") ".")) (section 4 "Grouping Rules" (def (sig (syntax "(informal options . body)" (id informal))) (p "This is the wrapping rule for all further rules. It creates a " (tt "form") " tag according to the alist " (tt "options") ". The available keys are:") (dl (dt (tt "prefix")) (dd "a string which will be prepended to all of this form's input elements' " (tt "name") " and " (tt "id") " attributes.") (dt (tt "@")) (dd "the SXML attribute list for the resulting form tag, passed verbatim; use this to set the form's " (tt "action") " etc.")) (p "Alternatively " (tt "options") " may be an immediate attribute list if no futher configuration is needed.") (p "The " (tt "body") " should contain the form's input elements (see " (int-link "#input-element-rules" "Input Element Rules") ").")) (def (sig (syntax "(fields #!optional legend . elements)" (id fields))) (p "This rule should be used inside an " (tt "informal") "'s body to group a set of input " (tt "elements") ". The resulting SXML will wrap them in a " (tt "fieldset") " element, possibly with a " (tt "legend") ". The " (tt "elements") " are then wrapped in an " (tt "ol") " elements, thus " (tt "elements") " must be a list of " (tt "li") " elements. This is sensible because all sxml-informal's input element rules transform into input elements " (tt "li") " wrapped elements."))) (section 4 "Input Element Rules" (p "All following rules transform to differnt kinds of input elements wrapped in an " (tt "<li>") " element. Its " (tt "class") " attribute is set to the input's type (e.g. " (tt "\"string\"") " or " (tt "\"text\"") ") and name. Further classes may be set depending on certain conditions (see below).") (p "All input element rules accept a " (tt "name") " argument which is used to for the element's " (tt "name") " and " (tt "id") " attributes, possibly prefixed by the surrounding " (tt "informal") " rule's prefix name. Additionally, at least the following keyword arguments are accepted:") (dl (dt "label") (dd "The text which is used for the " (tt "label") " element attached to the respective input element. When this is " (tt "#f") ", no label element is generated. Default value: " (tt "#f")) (dt "value") (dd "The input element's current value. If this is " (tt "#f") ", no value is set. Default: " (tt "#f")) (dt "error") (dd "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 " (tt "<span class=\"error\">") ". Two or more errors are wrapped in an " (tt "<ul class=\"errors\">") " and each error is then made an " (tt "<li>") " of that list. All non-false values will attach the class " (tt "\"invalid\"") " to the parent " (tt "<li>") ". When this is " (tt "#f") ", this argument doesn't have any effect.  Default: {{#f}")) (p "The basic expansion of input elements is thus something like this:") (pre "    (li (@ (class \"<type> <name> <invalid>\"))\n       <label>\n       <input>\n       <errors>)") (p "Some elements' label follows the input element rather than preceding it (e.g. for checkboxes and radio buttons).") (def (sig (procedure "(string name #!key value label error)" (id string)) (procedure "(password name #!key value label error)" (id password))) (p "These rules translate into input elements of the respective types " (tt "text") " or " (tt "password") " wrapped in the element markup described under " (int-link "#input-element-rules" "Input Element Rules") ". The input element expansion is") (pre "   (input (@ (type <type>) (id <name>) (name <name>) (value <value>)))")) (def (sig (procedure "(checkbox #!key value label error checked)" (id checkbox))) (p "This rule expands into a checkbox input element, followed by its label, wrapped in the element markup described under " (int-link "#input-element-rules" "Input Element Rules") ".  It accepts the following additional keyword arguments:") (dl (dt "checked") (dd "determines whether the checkbox is checked. Default: " (tt "#f"))) (p "The input element expansion is") (pre "   (input (@ (type \"checkbox\") (id <name>) (name <name>) (value <value>) [(checked \"checked\")]))")) (def (sig (procedure "(radio #!key value suffix label error checked)" (id radio))) (p "This rule expands into a radio button element, followed by its label, wrapped in the element markup described under " (int-link "#input-element-rules" "Input Element Rules") ". It accepts the following additional keyword arguments:") (dl (dt "checked") (dd "determines whether the checkbox is checked. Default: " (tt "#f")) (dt "suffix") (dd "the suffix for this input's " (tt "id") " attribute. Default: " (tt "(conc \"-\" value)"))) (p "The input element expansion is") (pre "   (input (@ (type \"radio\") (id <id>) (name <name>) (value <value>) [(checked \"checked\")]))")) (def (sig (procedure "(hidden name value)" (id hidden))) (p "This rule expands into a hidden field element without any wrapping like this:") (pre "   (input (@ (type \"hidden\") (id <id>) (name <name>) (value <value>)))")) (def (sig (procedure "(text name #!key value label error)" (id text))) (p "This rule translates into a " (tt "textarea") " element wrapped in the element markup described under " (int-link "#input-element-rules" "Input Element Rules") ". The textarea element expansion is") (pre "   (textarea (@ (id <name>) (name <name>)) <value>)")) (def (sig (procedure "(select name #!key options value label error)" (id select))) (p "This rule translates into a " (tt "select") " element wrapped in the element markup described under " (int-link "#input-element-rules" "Input Element Rules") ". It accepts the following additional keyword arguments:") (dl (dt "options") (dd "an alist ((<value> <text>) ...) which is turned into the " (tt "select") "'s " (tt "option") " elements. ") (dt "value") (dd "is used to determine on which " (tt "option") " element the " (tt "selected") " attribute is set by comparing it to the values given in " (tt "options") ".")) (p "The select element expansion is") (pre "   (select (@ (id <name>) (name <name>)) \n    [(option (@ (value <value>)) <text>) ...])\n   ")) (def (sig (procedure "(submit label #!key name)" (id submit))) (p "This rule translates into a submit input element wrapped in the element markup described under " (int-link "#input-element-rules" "Input Element Rules") ". The input element expansion is") (pre "   (input (@ (type \"submit\") (id <name>) (name <name>) (value <label>)))")))) (section 3 "Example" (highlight scheme "    \n(use sxml-transforms sxml-informal)\n\n(pre-post-order* '(informal (@ (action \"/postings\") (method \"POST\"))\n                            (fields \"Posting\"\n                                    (string \"author\" label: \"Your name\")\n                                    (string \"title\" label: \"Title\")\n                                    (text \"body\" label: \"Text\"))\n\n                            (fields (submit \"Save\")\n                                    (submit \"Publish\" name: \"publish\")))\n                 informal-rules)") (p "Result:") (highlight scheme "    \n(form (@ (action \"/postings\") (method \"POST\"))\n      (fieldset (legend \"Posting\")\n                (ol (li (@ (class \"string author\")) \n                        (label (@ (for \"author\")) \"Your name\")\n                        (input (@ (type \"text\") (id \"author\") (name \"author\"))))\n                    (li (@ (class \"string title\"))\n                        (label (@ (for \"title\")) \"Title\")\n                        (input (@ (type \"text\") (id \"title\") (name \"title\"))))\n                    (li (@ (class \"text body\")) \n                        (label (@ (for \"body\")) \"Text\")\n                        (textarea (@ (id \"body\") (name \"body\")) #f))))\n      (fieldset (ol (li (@ (class \"submit commit\"))\n                        (input (@ (type \"submit\") (id \"commit\") (name \"commit\") (value \"Save\"))))\n                    (li (@ (class \"submit publish\")) \n                        (input (@ (type \"submit\") (id \"publish\") (name \"publish\") (value \"Publish\")))))))"))))