basis/html/components/components-docs.factor

   1 ! Copyright (C) 2008 Your name.
   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 link to an object stored at a value, with the link title and URL determined by 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 { $subsection link }
  45 "The link title and URL are determined by passing the object to a pair of generic words:"
  46 { $subsection link-title }
  47 { $subsection link-href }
  48 "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." ;
  49
  50 HELP: comparison
  51 { $description "Comparison components render diffs output by the " { $link diff } " word." } ;
  52
  53 HELP: farkup
  54 { $description "Farkup components render " { $link "farkup" } "." } ;
  55
  56 HELP: hidden
  57 { $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." } ;
  58
  59 HELP: html
  60 { $description "HTML components render HTML verbatim, without any escaping. Care must be taken to only render trusted input, to avoid cross-site scripting attacks." } ;
  61
  62 HELP: inspector
  63 { $description "Inspector components render an arbitrary object by passing it to the " { $link describe } " word." } ;
  64
  65 HELP: label
  66 { $description "Label components render an object as a piece of text by passing it to the " { $link present } " word." } ;
  67
  68 HELP: render
  69 { $values { "name" "a value name" } { "renderer" "a component renderer" } }
  70 { $description "Renders an HTML component to the " { $link output-stream } "." } ;
  71
  72 HELP: render*
  73 { $values { "value" "a value" } { "name" "a value name" } { "renderer" "a component renderer" } { "xml" "an XML chunk" } }
  74 { $contract "Renders an HTML component, outputting an XHTML snippet." } ;
  75
  76 ARTICLE: "html.components" "HTML components"
  77 "The " { $vocab-link "html.components" } " vocabulary provides various HTML form components."
  78 $nl
  79 "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."
  80 $nl
  81 "Rendering components:"
  82 { $subsection render }
  83 "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" } ")."
  84 $nl
  85 "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."
  86 $nl
  87 "Singleton components:"
  88 { $subsection hidden }
  89 { $subsection link }
  90 { $subsection inspector }
  91 { $subsection comparison }
  92 { $subsection html }
  93 "Tuple components:"
  94 { $subsection field }
  95 { $subsection password }
  96 { $subsection textarea }
  97 { $subsection choice }
  98 { $subsection checkbox }
  99 { $subsection code }
 100 { $subsection farkup }
 101 "Creating custom components:"
 102 { $subsection render* }
 103 "Custom components can emit HTML using the " { $vocab-link "html.elements" } " vocabulary." ;
 104
 105 ABOUT: "html.components"