raw/mann/html.n

   1 '\" -*- tcl -*- doctools manpage
   2 '\"
   3 '\" Generated from ./modules/html/html.man by mpexpand with fmt.nroff
   4 '\"
   5 .so man.macros
   6 .TH "html" n 1.2.1 html "HTML Generation"
   7 .BS
   8 .SH NAME
   9 html \- Procedures to generate HTML structures
  10 .SH "SYNOPSIS"
  11 package require \fBTcl 8.2\fR
  12 .sp
  13 package require \fBhtml ?1.2.1?\fR
  14 .sp
  15 \fB::html::author\fR \fIauthor\fR\fR
  16 .sp
  17 \fB::html::bodyTag\fR \fIargs\fR\fR
  18 .sp
  19 \fB::html::cell\fR \fIparam value\fR ?\fItag\fR?\fR
  20 .sp
  21 \fB::html::checkbox\fR \fIname value\fR\fR
  22 .sp
  23 \fB::html::checkSet\fR \fIkey sep list\fR\fR
  24 .sp
  25 \fB::html::checkValue\fR \fIname\fR ?\fIvalue\fR?\fR
  26 .sp
  27 \fB::html::closeTag\fR \fR
  28 .sp
  29 \fB::html::default\fR \fIkey\fR ?\fIparam\fR?\fR
  30 .sp
  31 \fB::html::description\fR \fIdescription\fR\fR
  32 .sp
  33 \fB::html::end\fR \fR
  34 .sp
  35 \fB::html::eval\fR \fIarg\fR ?\fIargs\fR?\fR
  36 .sp
  37 \fB::html::extractParam\fR \fIparam key\fR ?\fIvarName\fR?\fR
  38 .sp
  39 \fB::html::font\fR \fIargs\fR\fR
  40 .sp
  41 \fB::html::for\fR \fIstart test next body\fR\fR
  42 .sp
  43 \fB::html::foreach\fR \fIvarlist1 list1\fR ?\fIvarlist2 list2 ...\fR? \fIbody\fR\fR
  44 .sp
  45 \fB::html::formValue\fR \fIname\fR ?\fIdefvalue\fR?\fR
  46 .sp
  47 \fB::html::getFormInfo\fR \fIargs\fR\fR
  48 .sp
  49 \fB::html::getTitle\fR \fR
  50 .sp
  51 \fB::html::h\fR \fIlevel string\fR ?\fIparam\fR?\fR
  52 .sp
  53 \fB::html::h1\fR \fIstring\fR ?\fIparam\fR?\fR
  54 .sp
  55 \fB::html::h2\fR \fIstring\fR ?\fIparam\fR?\fR
  56 .sp
  57 \fB::html::h3\fR \fIstring\fR ?\fIparam\fR?\fR
  58 .sp
  59 \fB::html::h4\fR \fIstring\fR ?\fIparam\fR?\fR
  60 .sp
  61 \fB::html::h5\fR \fIstring\fR ?\fIparam\fR?\fR
  62 .sp
  63 \fB::html::h6\fR \fIstring\fR ?\fIparam\fR?\fR
  64 .sp
  65 \fB::html::hdrRow\fR \fIargs\fR\fR
  66 .sp
  67 \fB::html::head\fR \fItitle\fR\fR
  68 .sp
  69 \fB::html::headTag\fR \fIstring\fR\fR
  70 .sp
  71 \fB::html::if\fR \fIexpr1 body1\fR ?\fBelseif\fR \fIexpr2 body2 ...\fR? ?\fBelse\fR \fIbodyN\fR?\fR
  72 .sp
  73 \fB::html::keywords\fR \fIargs\fR\fR
  74 .sp
  75 \fB::html::mailto\fR \fIemail\fR ?\fIsubject\fR?\fR
  76 .sp
  77 \fB::html::meta\fR \fIargs\fR\fR
  78 .sp
  79 \fB::html::minorMenu\fR \fIlist\fR ?\fIsep\fR?\fR
  80 .sp
  81 \fB::html::minorList\fR \fIlist\fR ?\fIordered\fR?\fR
  82 .sp
  83 \fB::html::openTag\fR \fItag args\fR\fR
  84 .sp
  85 \fB::html::passwordInput\fR ?\fIname\fR?\fR
  86 .sp
  87 \fB::html::passwordInputRow\fR \fIlabel\fR ?\fIname\fR?\fR
  88 .sp
  89 \fB::html::quoteFormValue\fR \fIvalue\fR\fR
  90 .sp
  91 \fB::html::radioSet\fR \fIkey sep list\fR\fR
  92 .sp
  93 \fB::html::radioValue\fR \fIname value\fR\fR
  94 .sp
  95 \fB::html::refresh\fR \fIseconds url\fR\fR
  96 .sp
  97 \fB::html::init\fR ?\fIlist\fR?\fR
  98 .sp
  99 \fB::html::row\fR \fIargs\fR\fR
 100 .sp
 101 \fB::html::paramRow\fR \fIlist\fR ?\fIrparam\fR? ?\fIcparam\fR?\fR
 102 .sp
 103 \fB::html::select\fR \fIname param choices\fR ?\fIcurrent\fR?\fR
 104 .sp
 105 \fB::html::selectPlain\fR \fIname param choices\fR ?\fIcurrent\fR?\fR
 106 .sp
 107 \fB::html::submit\fR \fIlabel\fR ?\fIname\fR?\fR
 108 .sp
 109 \fB::html::set\fR \fIvar val\fR\fR
 110 .sp
 111 \fB::html::tableFromArray\fR \fIarrname\fR ?\fIparam\fR? ?\fIpat\fR?\fR
 112 .sp
 113 \fB::html::tableFromList\fR \fIquerylist\fR ?\fIparam\fR?\fR
 114 .sp
 115 \fB::html::textarea\fR \fIname\fR ?\fIparam\fR? ?\fIcurrent\fR?\fR
 116 .sp
 117 \fB::html::textInput\fR \fIname args\fR\fR
 118 .sp
 119 \fB::html::textInputRow\fR \fIlabel name args\fR\fR
 120 .sp
 121 \fB::html::title\fR \fItitle\fR\fR
 122 .sp
 123 \fB::html::varEmpty\fR \fIname\fR\fR
 124 .sp
 125 \fB::html::while\fR \fItest body\fR\fR
 126 .sp
 127 .BE
 128 .SH "DESCRIPTION"
 129 .PP
 130 The package \fBhtml\fR provides commands that generate HTML.
 131 These commands typically return an HTML string as their result. In
 132 particular, they do not output their result to \fBstdout\fR.
 133 .PP
 134 The command \fB::html::init\fR should be called early to initialize
 135 the module.  You can also use this procedure to define default values
 136 for HTML tag parameters.
 137 .TP
 138 \fB::html::author\fR \fIauthor\fR\fR
 139 \fBSide effect only\fR.  Call this before \fB::html::head\fR to
 140 define an author for the page.  The author is noted in a comment in
 141 the HEAD section.
 142 .TP
 143 \fB::html::bodyTag\fR \fIargs\fR\fR
 144 Generate a BODY tag.  The tag parameters are taken from \fIargs\fR or
 145 from the body.* attributes define with \fB::html::init\fR.
 146 .TP
 147 \fB::html::cell\fR \fIparam value\fR ?\fItag\fR?\fR
 148 Generate a TD (or TH) tag, a value, and a closing TD (or TH) tag. The
 149 tag parameters come from \fIparam\fR or TD.* attributes defined with
 150 \fB::html::init\fR.  This uses \fB::html::font\fR to insert a standard
 151 FONT tag into the table cell. The \fItag\fR argument defaults to "td".
 152 .TP
 153 \fB::html::checkbox\fR \fIname value\fR\fR
 154 Generate a CHECKBOX form element with the specified name and value.
 155 This uses \fB::html::checkValue\fR.
 156 .TP
 157 \fB::html::checkSet\fR \fIkey sep list\fR\fR
 158 Generate a set of CHECKBOX form elements and associated labels.  The
 159 \fIlist\fR should contain an alternating list of labels and values.
 160 This uses \fB::html::checkbox\fR.
 161 .TP
 162 \fB::html::checkValue\fR \fIname\fR ?\fIvalue\fR?\fR
 163 Generate the "name=\fIname\fR value=\fIvalue\fR for a CHECKBOX form
 164 element.  If the CGI variable \fIname\fR has the value \fIvalue\fR,
 165 then SELECTED is added to the return value. \fIvalue\fR defaults to
 166 "1".
 167 .TP
 168 \fB::html::closeTag\fR \fR
 169 Pop a tag off the stack created by \fB::html::openTag\fR and generate
 170 the corresponding close tag (e.g., /BODY).
 171 .TP
 172 \fB::html::default\fR \fIkey\fR ?\fIparam\fR?\fR
 173 This procedure is used by \fB::html::tagParam\fR to generate the name,
 174 value list of parameters for a tag.  The \fB::html::default\fR
 175 procedure is used to generate default values for those items not
 176 already in \fIparam\fR.  If the value identified by \fIkey\fR matches
 177 a value in \fIparam\fR then this procedure returns the empty string.
 178 Otherwise, it returns a "parameter=value" string for a form element
 179 identified by \fIkey\fR.  The \fIkey\fR has the form "tag.parameter"
 180 (e.g., body.bgcolor).  Use \fB::html::init\fR to register default
 181 values. \fIparam\fR defaults to the empty string.
 182 .TP
 183 \fB::html::description\fR \fIdescription\fR\fR
 184 \fBSide effect only\fR.  Call this before \fB::html::head\fR to
 185 define a description META tag for the page.  This tag is generated
 186 later in the call to \fB::html::head\fR.
 187 .TP
 188 \fB::html::end\fR \fR
 189 Pop all open tags from the stack and generate the corresponding close
 190 HTML tags, (e.g., </body></html>).
 191 .TP
 192 \fB::html::eval\fR \fIarg\fR ?\fIargs\fR?\fR
 193 This procedure is similar to the built-in Tcl \fBeval\fR command.  The
 194 only difference is that it returns "" so it can be called from an HTML
 195 template file without appending unwanted results.
 196 .TP
 197 \fB::html::extractParam\fR \fIparam key\fR ?\fIvarName\fR?\fR
 198 This is a parsing procedure that extracts the value of \fIkey\fR from
 199 \fIparam\fR, which is a HTML-style "name=quotedvalue" list.
 200 \fIvarName\fR is used as the name of a Tcl variable that is changed to
 201 have the value found in the parameters.  The function returns 1 if the
 202 parameter was found in \fIparam\fR, otherwise it returns 0.  If the
 203 \fIvarName\fR is not specified, then \fIkey\fR is used as the variable
 204 name.
 205 .TP
 206 \fB::html::font\fR \fIargs\fR\fR
 207 Generate a standard FONT tag.  The parameters to the tag are taken
 208 from \fIargs\fR and the HTML defaults defined with \fB::html::init\fR.
 209 .TP
 210 \fB::html::for\fR \fIstart test next body\fR\fR
 211 This procedure is similar to the built-in Tcl \fBfor\fR control
 212 structure.  Rather than evaluating the body, it returns the subst'ed
 213 \fIbody\fR. Each iteration of the loop causes another string to be
 214 concatenated to the result value.
 215 .TP
 216 \fB::html::foreach\fR \fIvarlist1 list1\fR ?\fIvarlist2 list2 ...\fR? \fIbody\fR\fR
 217 This procedure is similar to the built-in Tcl \fBforeach\fR control
 218 structure.  Rather than evaluating the body, it returns the subst'ed
 219 \fIbody\fR.  Each iteration of the loop causes another string to be
 220 concatenated to the result value.
 221 .TP
 222 \fB::html::formValue\fR \fIname\fR ?\fIdefvalue\fR?\fR
 223 Return a name and value pair, where the value is initialized from
 224 existing CGI data, if any.  The result has this form:
 225 .sp
 226 .nf
 227   name="fred" value="freds value"
 228 .fi
 229 .TP
 230 \fB::html::getFormInfo\fR \fIargs\fR\fR
 231 Generate hidden fields to capture form values.  If \fIargs\fR is
 232 empty, then hidden fields are generated for all CGI values.  Otherwise
 233 args is a list of string match patterns for form element names.
 234 .TP
 235 \fB::html::getTitle\fR \fR
 236 Return the title string, with out the surrounding TITLE tag, set with
 237 a previous call to \fB::html::title\fR.
 238 .TP
 239 \fB::html::h\fR \fIlevel string\fR ?\fIparam\fR?\fR
 240 Generate a heading (e.g., H1) tag.  The \fIstring\fR is nested in the
 241 heading, and \fIparam\fR is used for the tag parameters.
 242 .TP
 243 \fB::html::h1\fR \fIstring\fR ?\fIparam\fR?\fR
 244 Generate an H1 tag.  See \fB::html::h\fR.
 245 .TP
 246 \fB::html::h2\fR \fIstring\fR ?\fIparam\fR?\fR
 247 Generate an H2 tag.  See \fB::html::h\fR.
 248 .TP
 249 \fB::html::h3\fR \fIstring\fR ?\fIparam\fR?\fR
 250 Generate an H3 tag.  See \fB::html::h\fR.
 251 .TP
 252 \fB::html::h4\fR \fIstring\fR ?\fIparam\fR?\fR
 253 Generate an H4 tag.  See \fB::html::h\fR.
 254 .TP
 255 \fB::html::h5\fR \fIstring\fR ?\fIparam\fR?\fR
 256 Generate an H5 tag.  See \fB::html::h\fR.
 257 .TP
 258 \fB::html::h6\fR \fIstring\fR ?\fIparam\fR?\fR
 259 Generate an H6 tag.  See \fB::html::h\fR.
 260 .TP
 261 \fB::html::hdrRow\fR \fIargs\fR\fR
 262 Generate a table row, including TR and TH tags.
 263 Each value in \fIargs\fR is place into its own table cell.
 264 This uses \fB::html::cell\fR.
 265 .TP
 266 \fB::html::head\fR \fItitle\fR\fR
 267 Generate the HEAD section that includes the page TITLE.
 268 If previous calls have been made to
 269 \fB::html::author\fR,
 270 \fB::html::keywords\fR,
 271 \fB::html::description\fR,
 272 or
 273 \fB::html::meta\fR
 274 then additional tags are inserted into the HEAD section.
 275 This leaves an open HTML tag pushed on the stack with
 276 \fB::html::openTag\fR.
 277 .TP
 278 \fB::html::headTag\fR \fIstring\fR\fR
 279 Save a tag for inclusion in the HEAD section generated by
 280 \fB::html::head\fR.  The \fIstring\fR is everything in the tag except
 281 the enclosing angle brackets, < >.
 282 .TP
 283 \fB::html::if\fR \fIexpr1 body1\fR ?\fBelseif\fR \fIexpr2 body2 ...\fR? ?\fBelse\fR \fIbodyN\fR?\fR
 284 This procedure is similar to the built-in Tcl \fBif\fR control
 285 structure.  Rather than evaluating the body of the branch that is
 286 taken, it returns the subst'ed \fIbody\fR.  Note that the syntax is
 287 slightly more restrictive than that of the built-in Tcl \fBif\fR
 288 control structure.
 289 .TP
 290 \fB::html::keywords\fR \fIargs\fR\fR
 291 \fBSide effect only\fR.  Call this before \fB::html::head\fR to
 292 define a keyword META tag for the page.  The META tag is included in
 293 the result of \fB::html::head\fR.
 294 .TP
 295 \fB::html::mailto\fR \fIemail\fR ?\fIsubject\fR?\fR
 296 Generate a hypertext link to a mailto: URL.
 297 .TP
 298 \fB::html::meta\fR \fIargs\fR\fR
 299 \fBSide effect only\fR.  Call this before \fB::html::head\fR to
 300 define a META tag for the page.  The \fIargs\fR is a Tcl-style name,
 301 value list that is used for the name= and value= parameters for the
 302 META tag.  The META tag is included in the result of
 303 \fB::html::head\fR.
 304 .TP
 305 \fB::html::minorMenu\fR \fIlist\fR ?\fIsep\fR?\fR
 306 Generate a series of hypertext links.  The \fIlist\fR is a Tcl-style
 307 name, value list of labels and urls for the links.  The \fIsep\fR is
 308 the text to put between each link. It defaults to " | ".
 309 .TP
 310 \fB::html::minorList\fR \fIlist\fR ?\fIordered\fR?\fR
 311 Generate an ordered or unordered list of links.  The \fIlist\fR is a
 312 Tcl-style name, value list of labels and urls for the links.
 313 \fIordered\fR is a boolean used to choose between an ordered or
 314 unordered list. It defaults to \fBfalse\fR.
 315 .TP
 316 \fB::html::openTag\fR \fItag args\fR\fR
 317 Push \fItag\fR onto a stack and generate the opening tag for
 318 \fItag\fR.  Use \fB::html::closeTag\fR to pop the tag from the stack.
 319 .TP
 320 \fB::html::passwordInput\fR ?\fIname\fR?\fR
 321 Generate an INPUT tag of type PASSWORD. The \fIname\fR defaults to
 322 "password".
 323 .TP
 324 \fB::html::passwordInputRow\fR \fIlabel\fR ?\fIname\fR?\fR
 325 Format a table row containing a label and an INPUT tag of type
 326 PASSWORD. The \fIname\fR defaults to "password".
 327 .TP
 328 \fB::html::quoteFormValue\fR \fIvalue\fR\fR
 329 Quote special characters in \fIvalue\fR by replacing them with HTML
 330 entities for quotes, ampersand, and angle brackets.
 331 .TP
 332 \fB::html::radioSet\fR \fIkey sep list\fR\fR
 333 Generate a set of INPUT tags of type RADIO and an associated text
 334 label.  All the radio buttons share the same \fIkey\fR for their name.
 335 The \fIsep\fR is text used to separate the elements.  The \fIlist\fR
 336 is a Tcl-style label, value list.
 337 .TP
 338 \fB::html::radioValue\fR \fIname value\fR\fR
 339 Generate the "name=\fIname\fR value=\fIvalue\fR for a RADIO form
 340 element.  If the CGI variable \fIname\fR has the value \fIvalue\fR,
 341 then SELECTED is added to the return value.
 342 .TP
 343 \fB::html::refresh\fR \fIseconds url\fR\fR
 344 Set up a refresh META tag. Call this before \fB::html::head\fR and the
 345 HEAD section will contain a META tag that causes the document to
 346 refresh in \fIseconds\fR seconds.  The \fIurl\fR is optional.  If
 347 specified, it specifies a new page to load after the refresh interval.
 348 .TP
 349 \fB::html::init\fR ?\fIlist\fR?\fR
 350 \fB::html::init\fR accepts a Tcl-style name-value list that defines
 351 values for items with a name of the form "tag.parameter".  For
 352 example, a default with key "body.bgcolor" defines the background
 353 color for the BODY tag.
 354 .TP
 355 \fB::html::row\fR \fIargs\fR\fR
 356 Generate a table row, including TR and TD tags.  Each value in
 357 \fIargs\fR is place into its own table cell. This uses
 358 \fB::html::cell\fR.
 359 .TP
 360 \fB::html::paramRow\fR \fIlist\fR ?\fIrparam\fR? ?\fIcparam\fR?\fR
 361 Generate a table row, including TR and TD tags. Each value in
 362 \fIlist\fR is placed into its own table cell. This uses
 363 \fB::html::cell\fR. The value of \fIrparam\fR is used as parameter for
 364 the TR tag. The value of \fIcparam\fR is passed to \fB::html::cell\fR
 365 as parameter for the TD tags.
 366 .TP
 367 \fB::html::select\fR \fIname param choices\fR ?\fIcurrent\fR?\fR
 368 Generate a SELECT form element and nested OPTION tags. The \fIname\fR
 369 and \fIparam\fR are used to generate the SELECT tag. The \fIchoices\fR
 370 list is a Tcl-style name, value list.
 371 .TP
 372 \fB::html::selectPlain\fR \fIname param choices\fR ?\fIcurrent\fR?\fR
 373 Like \fB::html::select\fR except that \fIchoices\fR is a Tcl list of
 374 values used for the OPTION tags.  The label and the value for each
 375 OPTION are the same.
 376 .TP
 377 \fB::html::submit\fR \fIlabel\fR ?\fIname\fR?\fR
 378 Generate an INPUT tag of type SUBMIT. \fIname\fR defaults to "submit".
 379 .TP
 380 \fB::html::set\fR \fIvar val\fR\fR
 381 This procedure is similar to the built-in Tcl \fBset\fR command.  The
 382 main difference is that it returns "" so it can be called from an HTML
 383 template file without appending unwanted results.  The other
 384 difference is that it must take two arguments.
 385 .TP
 386 \fB::html::tableFromArray\fR \fIarrname\fR ?\fIparam\fR? ?\fIpat\fR?\fR
 387 Generate a TABLE and nested rows to display a Tcl array. The
 388 \fIparam\fR are for the TABLE tag. The \fIpat\fR is a
 389 \fBstring match\fR pattern used to select array elements. It
 390 defaults to "*".
 391 .TP
 392 \fB::html::tableFromList\fR \fIquerylist\fR ?\fIparam\fR?\fR
 393 Generate a TABLE and nested rows to display \fIquerylist\fR, which is
 394 a Tcl-style name, value list.  The \fIparam\fR are for the TABLE tag.
 395 .TP
 396 \fB::html::textarea\fR \fIname\fR ?\fIparam\fR? ?\fIcurrent\fR?\fR
 397 Generate a TEXTAREA tag wrapped around its current values.
 398 .TP
 399 \fB::html::textInput\fR \fIname args\fR\fR
 400 Generate an INPUT form tag with type TEXT.  This uses
 401 \fB::html::formValue\fR.  The args is any additional tag attributes
 402 you want to put into the INPUT tag.
 403 .TP
 404 \fB::html::textInputRow\fR \fIlabel name args\fR\fR
 405 Generate an INPUT form tag with type TEXT formatted into a table row
 406 with an associated label.  The args is any additional tag attributes
 407 you want to put into the INPUT tag.
 408 .TP
 409 \fB::html::title\fR \fItitle\fR\fR
 410 \fBSide effect only\fR.  Call this before \fB::html::head\fR to
 411 define the TITLE for a page.
 412 .TP
 413 \fB::html::varEmpty\fR \fIname\fR\fR
 414 This returns 1 if the named variable either does not exist or has the
 415 empty string for its value.
 416 .TP
 417 \fB::html::while\fR \fItest body\fR\fR
 418 This procedure is similar to the built-in Tcl \fBwhile\fR control
 419 structure.  Rather than evaluating the body, it returns the subst'ed
 420 \fIbody\fR.  Each iteration of the loop causes another string to be
 421 concatenated to the result value.
 422 .SH "SEE ALSO"
 423 ncgi, htmlparse
 424 .SH "KEYWORDS"
 425 html, form, table, checkbox, radiobutton, checkbutton