basis/html/components/components-docs.factor

   1 ! Copyright (C) 2008 Slava Pestov
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax io.streams.string kernel strings
   4 urls lcs inspector present io ;
   5 IN: html.components
   6
   7 HELP: checkbox
   8 { $class-description "Checkbox components render a boolean value. The " { $slot "label" } " slot must be set to a string." } ;
   9
  10 HELP: choice
  11 { $class-description "Choice components render a popup menu or list box with either single or multiple selection."
  12 $nl
  13 "The " { $slot "multiple" } " slot determines whether multiple elements may be selected at once; if this is set to a true value, then the component value must be a sequence of strings, otherwise it must be a single string."
  14 $nl
  15 "The " { $slot "size" } " slot determines the number of items visible at one time; if neither this nor " { $slot "multiple" } " is set, the component is rendered as a popup menu rather than a list."
  16 $nl
  17 "The " { $slot "choices" } " slot determines all possible choices which may be selected. It names a value, rather than storing the choices directly." } ;
  18
  19 HELP: code
  20 { $class-description "Code components render string value with the " { $vocab-link "xmode.code2html" } " syntax highlighting vocabulary. The " { $slot "mode" } " slot names a value holding an XMode mode name." } ;
  21
  22 HELP: field
  23 { $class-description "Field components display a one-line editor for a string value. The " { $slot "size" } " slot determines the maximum displayed width of the field." } ;
  24
  25 HELP: password
  26 { $class-description "Password field components display a one-line editor which obscures the user's input. The " { $slot "size" } " slot determines the maximum displayed width of the field. Unlike other components, on failed validation, the contents of a password field are not sent back to the client. This is a security feature, intended to avoid revealing the password to potential snoopers who use the " { $strong "View Source" } " feature." } ;
  27
  28 HELP: textarea
  29 { $class-description "Text area components display a multi-line editor for a string value. The " { $slot "rows" } " and " { $slot "cols" } " properties determine the size of the text area." } ;
  30
  31 HELP: link
  32 { $description "Link components render a value responding to the " { $link link-title } " and " { $link link-href } " generic words. The optional " { $slot "target" } " slot is a target frame to open the link in." } ;
  33
  34 HELP: link-title
  35 { $values { "obj" object } { "string" string } }
  36 { $description "Outputs the title to render for a link to the object." } ;
  37
  38 HELP: link-href
  39 { $values { "obj" object } { "url" "a " { $link string } " or " { $link url } } }
  40 { $description "Outputs the URL to render for a link to the object." } ;
  41
  42 ARTICLE: "html.components.links" "Link components"
  43 "Link components render a link to an object."
  44 { $subsections link }
  45 "The link title and URL are determined by passing the object to a pair of generic words:"
  46 { $subsections
  47     link-title
  48     link-href
  49 }
  50 "The generic words provide methods on the " { $link string } " and " { $link url } " classes which treat the object as a URL. New methods can be defined for rendering links to custom data types." ;
  51
  52 HELP: comparison
  53 { $description "Comparison components render diffs output by the " { $link lcs-diff } " word." } ;
  54
  55 HELP: farkup
  56 { $description "Farkup components render " { $link "farkup" } "." } ;
  57
  58 HELP: hidden
  59 { $description "Hidden components render as a hidden form field. For example, a page for editing a weblog post might contain a hidden field with the post ID." } ;
  60
  61 HELP: html
  62 { $description "HTML components render HTML verbatim from a string, without any escaping. Care must be taken to only render trusted input, to avoid cross-site scripting attacks." } ;
  63
  64 HELP: xml
  65 { $description "XML components render XML verbatim, from an XML chunk. Care must be taken to only render trusted input, to avoid cross-site scripting attacks." } ;
  66
  67 HELP: inspector
  68 { $description "Inspector components render an arbitrary object by passing it to the " { $link describe } " word." } ;
  69
  70 HELP: label
  71 { $description "Label components render an object as a piece of text by passing it to the " { $link present } " word." } ;
  72
  73 HELP: render
  74 { $values { "name" "a value name" } { "renderer" "a component renderer" } }
  75 { $description "Renders an HTML component to the " { $link output-stream } "." } ;
  76
  77 HELP: render*
  78 { $values { "value" "a value" } { "name" "a value name" } { "renderer" "a component renderer" } { "xml" "an XML chunk" } }
  79 { $contract "Renders an HTML component, outputting an XHTML snippet." } ;
  80
  81 ARTICLE: "html.components" "HTML components"
  82 "The " { $vocab-link "html.components" } " vocabulary provides various HTML form components."
  83 $nl
  84 "Most web applications can use the " { $vocab-link "html.templates.chloe" } " templating framework instead of using this vocabulary directly. Where maximum flexibility is required, this vocabulary can be used together with the " { $vocab-link "html.templates.fhtml" } " templating framework."
  85 $nl
  86 "Rendering components:"
  87 { $subsections render }
  88 "Components render a named value, and the name of the value is passed in every time the component is rendered, rather than being associated with the component itself. Named values are taken from the current HTML form (see " { $link "html.forms" } ")."
  89 $nl
  90 "Component come in two varieties: singletons and tuples. Components with no configuration are singletons; they do not have to instantiated, rather the class word represents the component. Tuple components have to be instantiated and offer configuration options."
  91 $nl
  92 "Singleton components:"
  93 { $subsections
  94     hidden
  95     link
  96     inspector
  97     comparison
  98     html
  99     xml
 100 }
 101 "Tuple components:"
 102 { $subsections
 103     field
 104     password
 105     textarea
 106     choice
 107     checkbox
 108     code
 109     farkup
 110 }
 111 "Creating custom components:"
 112 { $subsections render* }
 113 "Custom components can emit HTML using the " { $vocab-link "xml.syntax" } " vocabulary." ;
 114
 115 ABOUT: "html.components"