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.5?
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::meta_name args
84 ::html::meta_equiv args
86 ::html::meta_charset charset
88 ::html::css href
90 ::html::css-clear
92 ::html::js href
94 ::html::js-clear
96 ::html::minorList list ?ordered?
98 ::html::minorMenu list ?sep?
100 ::html::nl2br string
102 ::html::openTag tag ?param?
104 ::html::paramRow list ?rparam? ?cparam?
106 ::html::passwordInput ?name?
108 ::html::passwordInputRow label ?name?
110 ::html::quoteFormValue value
112 ::html::radioSet key sep list
114 ::html::radioValue name value
116 ::html::refresh seconds url
118 ::html::row args
120 ::html::select name param choices ?current?
122 ::html::selectPlain name param choices ?current?
124 ::html::set var val
126 ::html::submit label ?name? ?title?
128 ::html::tableFromArray arrname ?param? ?pat?
130 ::html::tableFromList querylist ?param?
132 ::html::textarea name ?param? ?current?
134 ::html::textInput name value args
136 ::html::textInputRow label name value args
138 ::html::varEmpty name
140 ::html::while test body
142 ::html::doctype id
144 ::html::wrapTag tag ?text? ?args?
146______________________________________________________________________________
148
150 The package html provides commands that generate HTML. These commands
151 typically return an HTML string as their result. In particular, they do
152 not output their result to stdout.
153 The command ::html::init should be called early to initialize the mod‐
155 ule. You can also use this procedure to define default values for HTML
156 tag parameters.
157 ::html::author author
159 Side effect only. Call this before ::html::head to define an
160 author for the page. The author is noted in a comment in the
161 HEAD section.
162 ::html::bodyTag args
164 Generate a body tag. The tag parameters are taken from args or
165 from the body.* attributes define with ::html::init.
166 ::html::cell param value ?tag?
168 Generate a td (or th) tag, a value, and a closing td (or th)
169 tag. The tag parameters come from param or TD.* attributes de‐
170 fined with ::html::init. This uses ::html::font to insert a
171 standard font tag into the table cell. The tag argument defaults
172 to "td".
173 ::html::checkbox name value
175 Generate a checkbox form element with the specified name and
176 value. This uses ::html::checkValue.
177 ::html::checkSet key sep list
179 Generate a set of checkbox form elements and associated labels.
180 The list should contain an alternating list of labels and val‐
181 ues. This uses ::html::checkbox. All the checkbox buttons share
182 the same key for their name. The sep is text used to separate
183 the elements.
184 ::html::checkValue name ?value?
186 Generate the "name=name value=value" for a checkbox form ele‐
187 ment. If the CGI variable name has the value value, then SE‐
188 LECTED is added to the return value. value defaults to "1".
189 ::html::closeTag
191 Pop a tag off the stack created by ::html::openTag and generate
192 the corresponding close tag (e.g., </body>).
193 ::html::default key ?param?
195 This procedure is used by ::html::tagParam to generate the name,
196 value list of parameters for a tag. The ::html::default proce‐
197 dure is used to generate default values for those items not al‐
198 ready in param. If the value identified by key matches a value
199 in param then this procedure returns the empty string. Other‐
200 wise, it returns a "parameter=value" string for a form element
201 identified by key. The key has the form "tag.parameter" (e.g.,
202 body.bgcolor). Use ::html::init to register default values.
203 param defaults to the empty string.
204 ::html::description description
206 Side effect only. Call this before ::html::head to define a de‐
207 scription meta tag for the page. This tag is generated later in
208 the call to ::html::head.
209 ::html::end
211 Pop all open tags from the stack and generate the corresponding
212 close HTML tags, (e.g., </body></html>).
213 ::html::eval arg ?args?
215 This procedure is similar to the built-in Tcl eval command. The
216 only difference is that it returns "" so it can be called from
217 an HTML template file without appending unwanted results.
218 ::html::extractParam param key ?varName?
220 This is a parsing procedure that extracts the value of key from
221 param, which is a HTML-style "name=quotedvalue" list. varName
222 is used as the name of a Tcl variable that is changed to have
223 the value found in the parameters. The function returns 1 if
224 the parameter was found in param, otherwise it returns 0. If
225 the varName is not specified, then key is used as the variable
226 name.
227 ::html::font args
229 Generate a standard font tag. The parameters to the tag are
230 taken from args and the HTML defaults defined with ::html::init.
231 ::html::for start test next body
233 This procedure is similar to the built-in Tcl for control struc‐
234 ture. Rather than evaluating the body, it returns the subst'ed
235 body. Each iteration of the loop causes another string to be
236 concatenated to the result value.
237 ::html::foreach varlist1 list1 ?varlist2 list2 ...? body
239 This procedure is similar to the built-in Tcl foreach control
240 structure. Rather than evaluating the body, it returns the
241 subst'ed body. Each iteration of the loop causes another string
242 to be concatenated to the result value.
243 ::html::formValue name ?defvalue?
245 Return a name and value pair, where the value is initialized
246 from existing CGI data, if any. The result has this form:
247 name="fred" value="freds value"
251 ::html::getFormInfo args
254 Generate hidden fields to capture form values. If args is
255 empty, then hidden fields are generated for all CGI values.
256 Otherwise args is a list of string match patterns for form ele‐
257 ment names.
258 ::html::getTitle
260 Return the title string, with out the surrounding title tag, set
261 with a previous call to ::html::title.
262 ::html::h level string ?param?
264 Generate a heading (e.g., hlevel) tag. The string is nested in
265 the heading, and param is used for the tag parameters.
266 ::html::h1 string ?param?
268 Generate an h1 tag. See ::html::h.
269 ::html::h2 string ?param?
271 Generate an h2 tag. See ::html::h.
272 ::html::h3 string ?param?
274 Generate an h3 tag. See ::html::h.
275 ::html::h4 string ?param?
277 Generate an h4 tag. See ::html::h.
278 ::html::h5 string ?param?
280 Generate an h5 tag. See ::html::h.
281 ::html::h6 string ?param?
283 Generate an h6 tag. See ::html::h.
284 ::html::hdrRow args
286 Generate a table row, including tr and th tags. Each value in
287 args is place into its own table cell. This uses ::html::cell.
288 ::html::head title
290 Generate the head section that includes the page title. If pre‐
291 vious calls have been made to ::html::author, ::html::keywords,
292 ::html::description, or ::html::meta then additional tags are
293 inserted into the head section. This leaves an open html tag
294 pushed on the stack with ::html::openTag.
295 ::html::headTag string
297 Save a tag for inclusion in the head section generated by
298 ::html::head. The string is everything in the tag except the
299 enclosing angle brackets, < >.
300 ::html::html_entities string
302 This command replaces all special characters in the string with
303 their HTML entities and returns the modified text.
304 ::html::if expr1 body1 ?elseif expr2 body2 ...? ?else bodyN?
306 This procedure is similar to the built-in Tcl if control struc‐
307 ture. Rather than evaluating the body of the branch that is
308 taken, it returns the subst'ed body. Note that the syntax is
309 slightly more restrictive than that of the built-in Tcl if con‐
310 trol structure.
311 ::html::init ?list?
313 ::html::init accepts a Tcl-style name-value list that defines
314 values for items with a name of the form "tag.parameter". For
315 example, a default with key "body.bgcolor" defines the back‐
316 ground color for the body tag.
317 ::html::keywords args
319 Side effect only. Call this before ::html::head to define a
320 keyword meta tag for the page. The meta tag is included in the
321 result of ::html::head.
322 ::html::mailto email ?subject?
324 Generate a hypertext link to a mailto: URL.
325 ::html::meta args
327 Compatibility name for html::meta_name.
328 ::html::meta_name args
330 Side effect only. Call this before ::html::head to define a
331 meta tag for the page. The arguments (args) are a Tcl-style
332 name, value list that is used for the name= and content= at‐
333 tributes of the meta tag. The meta tag is included in the re‐
334 sult of ::html::head.
335 ::html::meta_equiv args
337 Side effect only. Call this before ::html::head to define a
338 meta tag for the page. The arguments (args) are a Tcl-style
339 name, value list that is used for the http-equiv= and content=
340 attributes of the meta tag. The meta tag is included in the re‐
341 sult of ::html::head.
342 ::html::meta_charset charset
344 Side effect only. Call this before ::html::head to define a
345 meta tag for the page. The charset is used with the charset=
346 attribute of the meta tag. The meta tag is included in the re‐
347 sult of ::html::head.
348 ::html::css href
350 Side effect only. Call this before ::html::head to define a
351 link tag for a linked CSS document. The href value is a HTTP
352 URL to a CSS document. The link tag is included in the result of
353 ::html::head.
354 Multiple calls of this command are allowed, enabling the use of
356 multiple CSS document references. In other words, the arguments
357 of multiple calls are accumulated, and do not overwrite each
358 other.
359 ::html::css-clear
361 Side effect only. Call this before ::html::head to clear all
362 links to CSS documents.
363 Multiple calls of this command are allowed, doing nothing after
365 the first of a sequence with no intervening ::html::css.
366 ::html::js href
368 Side effect only. Call this before ::html::head to define a
369 script tag for a linked JavaScript document. The href is a HTTP
370 URL to a JavaScript document. The script tag is included in the
371 result of ::html::head.
372 Multiple calls of this command are allowed, enabling the use of
374 multiple JavaScript document references. In other words, the ar‐
375 guments of multiple calls are accumulated, and do not overwrite
376 each other.
377 ::html::js-clear
379 Side effect only. Call this before ::html::head to clear all
380 links to JavaScript documents.
381 Multiple calls of this command are allowed, doing nothing after
383 the first of a sequence with no intervening ::html::js.
384 ::html::minorList list ?ordered?
386 Generate an ordered or unordered list of links. The list is a
387 Tcl-style name, value list of labels and urls for the links.
388 ordered is a boolean used to choose between an ordered or un‐
389 ordered list. It defaults to false.
390 ::html::minorMenu list ?sep?
392 Generate a series of hypertext links. The list is a Tcl-style
393 name, value list of labels and urls for the links. The sep is
394 the text to put between each link. It defaults to " | ".
395 ::html::nl2br string
397 This command replaces all line-endings in the string with a br
398 tag and returns the modified text.
399 ::html::openTag tag ?param?
401 Push tag onto a stack and generate the opening tag for tag. Use
402 ::html::closeTag to pop the tag from the stack. The second argu‐
403 ment provides any tag arguments, as a list whose elements are
404 formatted to be in the form "key=value".
405 ::html::paramRow list ?rparam? ?cparam?
407 Generate a table row, including tr and td tags. Each value in
408 list is placed into its own table cell. This uses ::html::cell.
409 The value of rparam is used as parameter for the tr tag. The
410 value of cparam is passed to ::html::cell as parameter for the
411 td tags.
412 ::html::passwordInput ?name?
414 Generate an input tag of type password. The name defaults to
415 "password".
416 ::html::passwordInputRow label ?name?
418 Format a table row containing a label and an input tag of type
419 password. The name defaults to "password".
420 ::html::quoteFormValue value
422 Quote special characters in value by replacing them with HTML
423 entities for quotes, ampersand, and angle brackets.
424 ::html::radioSet key sep list
426 Generate a set of input tags of type radio and an associated
427 text label. All the radio buttons share the same key for their
428 name. The sep is text used to separate the elements. The list
429 is a Tcl-style label, value list.
430 ::html::radioValue name value
432 Generate the "name=name value=value" for a radio form element.
433 If the CGI variable name has the value value, then SELECTED is
434 added to the return value.
435 ::html::refresh seconds url
437 Set up a refresh meta tag. Call this before ::html::head and the
438 HEAD section will contain a meta tag that causes the document to
439 refresh in seconds seconds. The url is optional. If specified,
440 it specifies a new page to load after the refresh interval.
441 ::html::row args
443 Generate a table row, including tr and td tags. Each value in
444 args is place into its own table cell. This uses ::html::cell.
445 Ignores any default information set up via ::html::init.
446 ::html::select name param choices ?current?
448 Generate a select form element and nested option tags. The name
449 and param are used to generate the select tag. The choices list
450 is a Tcl-style name, value list.
451 ::html::selectPlain name param choices ?current?
453 Like ::html::select except that choices is a Tcl list of values
454 used for the option tags. The label and the value for each op‐
455 tion are the same.
456 ::html::set var val
458 This procedure is similar to the built-in Tcl set command. The
459 main difference is that it returns "" so it can be called from
460 an HTML template file without appending unwanted results. The
461 other difference is that it must take two arguments.
462 ::html::submit label ?name? ?title?
464 Generate an input tag of type submit. The name defaults to
465 "submit". When a non-empty title string is specified the button
466 gains a title= attribute with that value.
467 ::html::tableFromArray arrname ?param? ?pat?
469 Generate a two-column table and nested rows to display a Tcl ar‐
470 ray. The table gets a heading that matches the array name, and
471 each generated row contains a name, value pair. The array names
472 are sorted (lsort without special options). The argument param
473 is for the table tag and has to contain a pre-formatted string.
474 The pat is a string match pattern used to select the array ele‐
475 ments to show in the table. It defaults to *, i.e. the whole ar‐
476 ray is shown.
477 ::html::tableFromList querylist ?param?
479 Generate a two-column table and nested rows to display
480 querylist, which is a Tcl dictionary. Each generated row con‐
481 tains a name, value pair. The information is shown in the same
482 order as specified in the dictionary. The argument param is for
483 the table tag and has to contain a pre-formatted string.
484 ::html::textarea name ?param? ?current?
486 Generate a textarea tag wrapped around its current values.
487 ::html::textInput name value args
489 Generate an input form tag with type text. This uses
490 ::html::formValue. The args is any additional tag attributes
491 you want to put into the input tag.
492 ::html::textInputRow label name value args
494 Generate an input form tag with type text formatted into a table
495 row with an associated label. The args is any additional tag
496 attributes you want to put into the input tag.
497 ::html::varEmpty name
499 This returns 1 if the named variable either does not exist or
500 has the empty string for its value.
501 ::html::while test body
503 This procedure is similar to the built-in Tcl while control
504 structure. Rather than evaluating the body, it returns the
505 subst'ed body. Each iteration of the loop causes another string
506 to be concatenated to the result value.
507 ::html::doctype id
509 This procedure can be used to build the standard DOCTYPE decla‐
510 ration string. It will return the standard declaration string
511 for the id, or throw an error if the id is not known. The fol‐
512 lowing id's are defined:
513 [1] HTML32
515 [2] HTML40
517 [3] HTML40T
519 [4] HTML40F
521 [5] HTML401
523 [6] HTML401T
525 [7] HTML401F
527 [8] XHTML10S
529 [9] XHTML10T
531 [10] XHTML10F
533 [11] XHTML11
535 [12] XHTMLB
537 ::html::wrapTag tag ?text? ?args?
539 A helper to wrap a text in a pair of open/close tags. The argu‐
540 ments (args) are a Tcl-style name, value list that is used to
541 provide attributes and associated values to the opening tag.
542 The result is a string with the open tag along with the optional
543 attributes, the optional text, and the closed tag.
544
546 This document, and the package it describes, will undoubtedly contain
547 bugs and other problems. Please report such in the category html of
548 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
549 also report any ideas for enhancements you may have for either package
550 and/or documentation.
551 When proposing code changes, please provide unified diffs, i.e the out‐
553 put of diff -u.
554 Note further that attachments are strongly preferred over inlined
556 patches. Attachments can be made by going to the Edit form of the
557 ticket immediately after its creation, and then using the left-most
558 button in the secondary navigation bar.
559
561 htmlparse, ncgi
562
564 checkbox, checkbutton, form, html, radiobutton, table
565
567 CGI programming
568tcllib 1.5 html(n)