1html(n) HTML Generation html(n)
2______________________________________________________________________________
6
8 html - Procedures to generate HTML structures
9
11 package require Tcl 8.2
12 package require html ?1.4.4?
14 ::html::author author
16 ::html::bodyTag args
18 ::html::cell param value ?tag?
20 ::html::checkbox name value
22 ::html::checkSet key sep list
24 ::html::checkValue name ?value?
26 ::html::closeTag
28 ::html::default key ?param?
30 ::html::description description
32 ::html::end
34 ::html::eval arg ?args?
36 ::html::extractParam param key ?varName?
38 ::html::font args
40 ::html::for start test next body
42 ::html::foreach varlist1 list1 ?varlist2 list2 ...? body
44 ::html::formValue name ?defvalue?
46 ::html::getFormInfo args
48 ::html::getTitle
50 ::html::h level string ?param?
52 ::html::h1 string ?param?
54 ::html::h2 string ?param?
56 ::html::h3 string ?param?
58 ::html::h4 string ?param?
60 ::html::h5 string ?param?
62 ::html::h6 string ?param?
64 ::html::hdrRow args
66 ::html::head title
68 ::html::headTag string
70 ::html::html_entities string
72 ::html::if expr1 body1 ?elseif expr2 body2 ...? ?else bodyN?
74 ::html::init ?list?
76 ::html::keywords args
78 ::html::mailto email ?subject?
80 ::html::meta args
82 ::html::css href
84 ::html::css-clear
86 ::html::js href
88 ::html::js-clear
90 ::html::minorList list ?ordered?
92 ::html::minorMenu list ?sep?
94 ::html::nl2br string
96 ::html::openTag tag ?param?
98 ::html::paramRow list ?rparam? ?cparam?
100 ::html::passwordInput ?name?
102 ::html::passwordInputRow label ?name?
104 ::html::quoteFormValue value
106 ::html::radioSet key sep list
108 ::html::radioValue name value
110 ::html::refresh seconds url
112 ::html::row args
114 ::html::select name param choices ?current?
116 ::html::selectPlain name param choices ?current?
118 ::html::set var val
120 ::html::submit label ?name?
122 ::html::tableFromArray arrname ?param? ?pat?
124 ::html::tableFromList querylist ?param?
126 ::html::textarea name ?param? ?current?
128 ::html::textInput name value args
130 ::html::textInputRow label name value args
132 ::html::varEmpty name
134 ::html::while test body
136 ::html::doctype id
138______________________________________________________________________________
140
142 The package html provides commands that generate HTML. These commands
143 typically return an HTML string as their result. In particular, they do
144 not output their result to stdout.
145 The command ::html::init should be called early to initialize the mod‐
147 ule. You can also use this procedure to define default values for HTML
148 tag parameters.
149 ::html::author author
151 Side effect only. Call this before ::html::head to define an
152 author for the page. The author is noted in a comment in the
153 HEAD section.
154 ::html::bodyTag args
156 Generate a body tag. The tag parameters are taken from args or
157 from the body.* attributes define with ::html::init.
158 ::html::cell param value ?tag?
160 Generate a td (or th) tag, a value, and a closing td (or th)
161 tag. The tag parameters come from param or TD.* attributes
162 defined with ::html::init. This uses ::html::font to insert a
163 standard font tag into the table cell. The tag argument defaults
164 to "td".
165 ::html::checkbox name value
167 Generate a checkbox form element with the specified name and
168 value. This uses ::html::checkValue.
169 ::html::checkSet key sep list
171 Generate a set of checkbox form elements and associated labels.
172 The list should contain an alternating list of labels and val‐
173 ues. This uses ::html::checkbox. All the checkbox buttons share
174 the same key for their name. The sep is text used to separate
175 the elements.
176 ::html::checkValue name ?value?
178 Generate the "name=name value=value" for a checkbox form ele‐
179 ment. If the CGI variable name has the value value, then
180 SELECTED is added to the return value. value defaults to "1".
181 ::html::closeTag
183 Pop a tag off the stack created by ::html::openTag and generate
184 the corresponding close tag (e.g., </body>).
185 ::html::default key ?param?
187 This procedure is used by ::html::tagParam to generate the name,
188 value list of parameters for a tag. The ::html::default proce‐
189 dure is used to generate default values for those items not
190 already in param. If the value identified by key matches a
191 value in param then this procedure returns the empty string.
192 Otherwise, it returns a "parameter=value" string for a form ele‐
193 ment identified by key. The key has the form "tag.parameter"
194 (e.g., body.bgcolor). Use ::html::init to register default val‐
195 ues. param defaults to the empty string.
196 ::html::description description
198 Side effect only. Call this before ::html::head to define a
199 description meta tag for the page. This tag is generated later
200 in the call to ::html::head.
201 ::html::end
203 Pop all open tags from the stack and generate the corresponding
204 close HTML tags, (e.g., </body></html>).
205 ::html::eval arg ?args?
207 This procedure is similar to the built-in Tcl eval command. The
208 only difference is that it returns "" so it can be called from
209 an HTML template file without appending unwanted results.
210 ::html::extractParam param key ?varName?
212 This is a parsing procedure that extracts the value of key from
213 param, which is a HTML-style "name=quotedvalue" list. varName
214 is used as the name of a Tcl variable that is changed to have
215 the value found in the parameters. The function returns 1 if
216 the parameter was found in param, otherwise it returns 0. If
217 the varName is not specified, then key is used as the variable
218 name.
219 ::html::font args
221 Generate a standard font tag. The parameters to the tag are
222 taken from args and the HTML defaults defined with ::html::init.
223 ::html::for start test next body
225 This procedure is similar to the built-in Tcl for control struc‐
226 ture. Rather than evaluating the body, it returns the subst'ed
227 body. Each iteration of the loop causes another string to be
228 concatenated to the result value.
229 ::html::foreach varlist1 list1 ?varlist2 list2 ...? body
231 This procedure is similar to the built-in Tcl foreach control
232 structure. Rather than evaluating the body, it returns the
233 subst'ed body. Each iteration of the loop causes another string
234 to be concatenated to the result value.
235 ::html::formValue name ?defvalue?
237 Return a name and value pair, where the value is initialized
238 from existing CGI data, if any. The result has this form:
239 name="fred" value="freds value"
243 ::html::getFormInfo args
246 Generate hidden fields to capture form values. If args is
247 empty, then hidden fields are generated for all CGI values.
248 Otherwise args is a list of string match patterns for form ele‐
249 ment names.
250 ::html::getTitle
252 Return the title string, with out the surrounding title tag, set
253 with a previous call to ::html::title.
254 ::html::h level string ?param?
256 Generate a heading (e.g., hlevel) tag. The string is nested in
257 the heading, and param is used for the tag parameters.
258 ::html::h1 string ?param?
260 Generate an h1 tag. See ::html::h.
261 ::html::h2 string ?param?
263 Generate an h2 tag. See ::html::h.
264 ::html::h3 string ?param?
266 Generate an h3 tag. See ::html::h.
267 ::html::h4 string ?param?
269 Generate an h4 tag. See ::html::h.
270 ::html::h5 string ?param?
272 Generate an h5 tag. See ::html::h.
273 ::html::h6 string ?param?
275 Generate an h6 tag. See ::html::h.
276 ::html::hdrRow args
278 Generate a table row, including tr and th tags. Each value in
279 args is place into its own table cell. This uses ::html::cell.
280 ::html::head title
282 Generate the head section that includes the page title. If pre‐
283 vious calls have been made to ::html::author, ::html::keywords,
284 ::html::description, or ::html::meta then additional tags are
285 inserted into the head section. This leaves an open html tag
286 pushed on the stack with ::html::openTag.
287 ::html::headTag string
289 Save a tag for inclusion in the head section generated by
290 ::html::head. The string is everything in the tag except the
291 enclosing angle brackets, < >.
292 ::html::html_entities string
294 This command replaces all special characters in the string with
295 their HTML entities and returns the modified text.
296 ::html::if expr1 body1 ?elseif expr2 body2 ...? ?else bodyN?
298 This procedure is similar to the built-in Tcl if control struc‐
299 ture. Rather than evaluating the body of the branch that is
300 taken, it returns the subst'ed body. Note that the syntax is
301 slightly more restrictive than that of the built-in Tcl if con‐
302 trol structure.
303 ::html::init ?list?
305 ::html::init accepts a Tcl-style name-value list that defines
306 values for items with a name of the form "tag.parameter". For
307 example, a default with key "body.bgcolor" defines the back‐
308 ground color for the body tag.
309 ::html::keywords args
311 Side effect only. Call this before ::html::head to define a
312 keyword meta tag for the page. The meta tag is included in the
313 result of ::html::head.
314 ::html::mailto email ?subject?
316 Generate a hypertext link to a mailto: URL.
317 ::html::meta args
319 Side effect only. Call this before ::html::head to define a
320 meta tag for the page. The args is a Tcl-style name, value list
321 that is used for the name= and value= parameters for the meta
322 tag. The meta tag is included in the result of ::html::head.
323 ::html::css href
325 Side effect only. Call this before ::html::head to define a
326 link tag for a linked CSS document. The href value is a HTTP
327 URL to a CSS document. The link tag is included in the result of
328 ::html::head.
329 Multiple calls of this command are allowed, enabling the use of
331 multiple CSS document references. In other words, the arguments
332 of multiple calls are accumulated, and do not overwrite each
333 other.
334 ::html::css-clear
336 Side effect only. Call this before ::html::head to clear all
337 links to CSS documents.
338 Multiple calls of this command are allowed, doing nothing after
340 the first of a sequence with no intervening ::html::css.
341 ::html::js href
343 Side effect only. Call this before ::html::head to define a
344 script tag for a linked JavaScript document. The href is a HTTP
345 URL to a JavaScript document. The script tag is included in the
346 result of ::html::head.
347 Multiple calls of this command are allowed, enabling the use of
349 multiple JavaScript document references. In other words, the
350 arguments of multiple calls are accumulated, and do not over‐
351 write each other.
352 ::html::js-clear
354 Side effect only. Call this before ::html::head to clear all
355 links to JavaScript documents.
356 Multiple calls of this command are allowed, doing nothing after
358 the first of a sequence with no intervening ::html::js.
359 ::html::minorList list ?ordered?
361 Generate an ordered or unordered list of links. The list is a
362 Tcl-style name, value list of labels and urls for the links.
363 ordered is a boolean used to choose between an ordered or
364 unordered list. It defaults to false.
365 ::html::minorMenu list ?sep?
367 Generate a series of hypertext links. The list is a Tcl-style
368 name, value list of labels and urls for the links. The sep is
369 the text to put between each link. It defaults to " | ".
370 ::html::nl2br string
372 This command replaces all line-endings in the string with a br
373 tag and returns the modified text.
374 ::html::openTag tag ?param?
376 Push tag onto a stack and generate the opening tag for tag. Use
377 ::html::closeTag to pop the tag from the stack. The second argu‐
378 ment provides any tag arguments, as a list whose elements are
379 formatted to be in the form "key=value".
380 ::html::paramRow list ?rparam? ?cparam?
382 Generate a table row, including tr and td tags. Each value in
383 list is placed into its own table cell. This uses ::html::cell.
384 The value of rparam is used as parameter for the tr tag. The
385 value of cparam is passed to ::html::cell as parameter for the
386 td tags.
387 ::html::passwordInput ?name?
389 Generate an input tag of type password. The name defaults to
390 "password".
391 ::html::passwordInputRow label ?name?
393 Format a table row containing a label and an input tag of type
394 password. The name defaults to "password".
395 ::html::quoteFormValue value
397 Quote special characters in value by replacing them with HTML
398 entities for quotes, ampersand, and angle brackets.
399 ::html::radioSet key sep list
401 Generate a set of input tags of type radio and an associated
402 text label. All the radio buttons share the same key for their
403 name. The sep is text used to separate the elements. The list
404 is a Tcl-style label, value list.
405 ::html::radioValue name value
407 Generate the "name=name value=value" for a radio form element.
408 If the CGI variable name has the value value, then SELECTED is
409 added to the return value.
410 ::html::refresh seconds url
412 Set up a refresh meta tag. Call this before ::html::head and the
413 HEAD section will contain a meta tag that causes the document to
414 refresh in seconds seconds. The url is optional. If specified,
415 it specifies a new page to load after the refresh interval.
416 ::html::row args
418 Generate a table row, including tr and td tags. Each value in
419 args is place into its own table cell. This uses ::html::cell.
420 Ignores any default information set up via ::html::init.
421 ::html::select name param choices ?current?
423 Generate a select form element and nested option tags. The name
424 and param are used to generate the select tag. The choices list
425 is a Tcl-style name, value list.
426 ::html::selectPlain name param choices ?current?
428 Like ::html::select except that choices is a Tcl list of values
429 used for the option tags. The label and the value for each
430 option are the same.
431 ::html::set var val
433 This procedure is similar to the built-in Tcl set command. The
434 main difference is that it returns "" so it can be called from
435 an HTML template file without appending unwanted results. The
436 other difference is that it must take two arguments.
437 ::html::submit label ?name?
439 Generate an input tag of type submit. name defaults to "submit".
440 ::html::tableFromArray arrname ?param? ?pat?
442 Generate a two-column table and nested rows to display a Tcl
443 array. The table gets a heading that matches the array name, and
444 each generated row contains a name, value pair. The array names
445 are sorted (lsort without special options). The argument param
446 is for the table tag and has to contain a pre-formatted string.
447 The pat is a string match pattern used to select the array ele‐
448 ments to show in the table. It defaults to *, i.e. the whole
449 array is shown.
450 ::html::tableFromList querylist ?param?
452 Generate a two-column table and nested rows to display
453 querylist, which is a Tcl dictionary. Each generated row con‐
454 tains a name, value pair. The information is shown in the same
455 order as specified in the dictionary. The argument param is for
456 the table tag and has to contain a pre-formatted string.
457 ::html::textarea name ?param? ?current?
459 Generate a textarea tag wrapped around its current values.
460 ::html::textInput name value args
462 Generate an input form tag with type text. This uses
463 ::html::formValue. The args is any additional tag attributes
464 you want to put into the input tag.
465 ::html::textInputRow label name value args
467 Generate an input form tag with type text formatted into a table
468 row with an associated label. The args is any additional tag
469 attributes you want to put into the input tag.
470 ::html::varEmpty name
472 This returns 1 if the named variable either does not exist or
473 has the empty string for its value.
474 ::html::while test body
476 This procedure is similar to the built-in Tcl while control
477 structure. Rather than evaluating the body, it returns the
478 subst'ed body. Each iteration of the loop causes another string
479 to be concatenated to the result value.
480 ::html::doctype id
482 This procedure can be used to build the standard DOCTYPE decla‐
483 ration string. It will return the standard declaration string
484 for the id, or throw an error if the id is not known. The fol‐
485 lowing id's are defined:
486 [1] HTML32
488 [2] HTML40
490 [3] HTML40T
492 [4] HTML40F
494 [5] HTML401
496 [6] HTML401T
498 [7] HTML401F
500 [8] XHTML10S
502 [9] XHTML10T
504 [10] XHTML10F
506 [11] XHTML11
508 [12] XHTMLB
510
512 This document, and the package it describes, will undoubtedly contain
513 bugs and other problems. Please report such in the category html of
514 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
515 also report any ideas for enhancements you may have for either package
516 and/or documentation.
517 When proposing code changes, please provide unified diffs, i.e the out‐
519 put of diff -u.
520 Note further that attachments are strongly preferred over inlined
522 patches. Attachments can be made by going to the Edit form of the
523 ticket immediately after its creation, and then using the left-most
524 button in the secondary navigation bar.
525
527 htmlparse, ncgi
528
530 checkbox, checkbutton, form, html, radiobutton, table
531
533 CGI programming
534tcllib 1.4.4 html(n)