basis/html/forms/forms-docs.factor

   1 IN: html.forms
   2 USING: help.markup help.syntax strings quotations kernel assocs ;
   3
   4 HELP: <form>
   5 { $values { "form" form } }
   6 { $description "Creates a new form. Usually " { $link with-form } " is used instead." } ;
   7
   8 HELP: form
   9 { $var-description "Variable holding current form. Bound by " { $link with-form } ", " { $link nest-form } " and " { $link begin-form } "." }
  10 { $class-description "The class of HTML forms. New instances are created by " { $link <form> } "." } ;
  11
  12 HELP: with-form
  13 { $values { "name" string } { "quot" quotation } }
  14 { $description "Runs the quotation in a new dynamic scope with the " { $link form } " variable rebound to the form stored in the value named " { $snippet "name" } "." } ;
  15
  16 HELP: nest-form
  17 { $values { "name" string } { "quot" quotation } }
  18 { $description "Runs the quotation in a new dynamic scope with the " { $link form } " variable rebound to a new form, which is subsequently stored in the value named " { $snippet "name" } "." }
  19 { $examples
  20     "The " { $vocab-link "webapps.pastebin" } " uses a form to display pastes; inside this form it nests another form for creating annotations, and fills in some default values for new annotations:"
  21     { $code
  22         "<page-action>"
  23         "    ["
  24         "        validate-integer-id"
  25         "        \"id\" value paste from-object"
  26         ""
  27         "        \"id\" value"
  28         "        \"new-annotation\" ["
  29         "            \"parent\" set-value"
  30         "            mode-names \"modes\" set-value"
  31         "            \"factor\" \"mode\" set-value"
  32         "        ] nest-form"
  33         "    ] >>init"
  34     }
  35 } ;
  36
  37 HELP: begin-form
  38 { $description "Begins a new form." } ;
  39
  40 HELP: value
  41 { $values { "name" string } { "value" object } }
  42 { $description "Gets a form value. This word is used to get form field values after validation." } ;
  43
  44 HELP: set-value
  45 { $values { "value" object } { "name" string } }
  46 { $description "Sets a form value. This word is used to preset form field values before rendering." } ;
  47
  48 HELP: from-object
  49 { $values { "object" object } }
  50 { $description "Sets the current form's values to the object's slot values." }
  51 { $examples
  52     "Here is a typical action implementation, which selects a golf course object from the database with the ID specified in the HTTP request, and renders a form with values from this object:"
  53     { $code
  54         "<page-action>"
  55         ""
  56         "    ["
  57         "        validate-integer-id"
  58         "        \"id\" value <golf-course>"
  59         "        select-tuple from-object"
  60         "    ] >>init"
  61         ""
  62         "    { golf \"view-course\" } >>template"
  63     }
  64 } ;
  65
  66 HELP: to-object
  67 { $values { "destination" object } { "names" "a sequence of value names" } }
  68 { $description "Stores the given sequence of form values into the slots of the object having the same names. This word is used to extract form field values after validation." } ;
  69
  70 HELP: with-each-value
  71 { $values { "name" string } { "quot" quotation } }
  72 { $description "Calls the quotation with each element of the value named " { $snippet "name" } "; the value must be a sequence. The quotation is called in a new dynamic scope with the " { $snippet "index" } " and " { $snippet "value" } " values set to the one-based index, and the sequence element in question, respectively." }
  73 { $notes "This word is used to implement the " { $snippet "t:each" } " tag of the " { $vocab-link "html.templates.chloe" } " templating system. It can also be called directly from " { $vocab-link "html.templates.fhtml" } " templates." } ;
  74
  75 HELP: with-each-object
  76 { $values { "name" string } { "quot" quotation } }
  77 { $description "Calls the quotation with each element of the value named " { $snippet "name" } "; the value must be a sequence. The quotation is called in a new dynamic scope where the object's slots become named values, as if " { $link from-object } " was called." }
  78 { $notes "This word is used to implement the " { $snippet "t:bind-each" } " tag of the " { $vocab-link "html.templates.chloe" } " templating system. It can also be called directly from " { $vocab-link "html.templates.fhtml" } " templates." } ;
  79
  80 HELP: validation-failed?
  81 { $values { "?" "a boolean" } }
  82 { $description "Tests if validation of the current form failed." } ;
  83
  84 HELP: validate-values
  85 { $values { "assoc" assoc } { "validators" "an assoc mapping value names to quotations" } }
  86 { $description "Validates values in the assoc by looking up the corresponding validation quotation, and storing the results in named values of the current form." } ;
  87
  88 HELP: validation-error
  89 { $values { "message" string } }
  90 { $description "Reports a validation error not associated with a specific form field." }
  91 { $notes "Such errors can be rendered by calling the " { $link render-validation-errors } " word." } ;
  92
  93 HELP: render-validation-errors
  94 { $description "Renders any validation errors reported by calls to the " { $link validation-error } " word." } ;
  95
  96 ARTICLE: "html.forms.forms" "HTML form infrastructure"
  97 "The below words are used to implement the " { $vocab-link "furnace.actions" } " vocabulary. Calling them directly is rarely necessary."
  98 $nl
  99 "Creating a new form:"
 100 { $subsections <form> }
 101 "Variable holding current form:"
 102 { $subsections form }
 103 "Working with forms:"
 104 { $subsections
 105     with-form
 106     begin-form
 107 }
 108 "Validation:"
 109 { $subsections
 110     validation-error
 111     validation-failed?
 112     validate-values
 113 } ;
 114
 115 ARTICLE: "html.forms.values" "HTML form values"
 116 "Form values are a central concept in the Furnace framework. Web actions primarily concern themselves with validating values, marshalling values to a database, and setting values for display in a form."
 117 $nl
 118 "Getting and setting values:"
 119 { $subsections
 120     value
 121     set-value
 122     from-object
 123     to-object
 124 }
 125 "Iterating over values; these words are used by " { $vocab-link "html.templates.chloe" } " to implement the " { $snippet "t:each" } " and " { $snippet "t:bind-each" } " tags:"
 126 { $subsections
 127     with-each-value
 128     with-each-object
 129 }
 130 "Nesting a form inside another form as a value:"
 131 { $subsections nest-form } ;
 132
 133 ARTICLE: "html.forms" "HTML forms"
 134 "The " { $vocab-link "html.forms" } " vocabulary implements support for rendering and validating HTML forms. The definition of a " { $emphasis "form" } " is a bit more general than the content of an " { $snippet "<form>" } " tag. Namely, a page which displays a database record without offering any editing capability is considered a form too; it consists entirely of read-only components."
 135 $nl
 136 "This vocabulary is an integral part of the " { $vocab-link "furnace" } " web framework. The " { $vocab-link "html.templates.chloe" } " vocabulary uses the HTML form words to implement various template tags. The words are also often used directly from web action implementations."
 137 $nl
 138 "This vocabulary can be used without either the Furnace framework or the HTTP server; for example, as part of a static HTML generation tool."
 139 { $subsections
 140     "html.forms.forms"
 141     "html.forms.values"
 142 } ;
 143
 144 ABOUT: "html.forms"