source: project/wiki/eggref/4/html-utils @ 30262

Last change on this file since 30262 was 30262, checked in by Mario Domenech Goulart, 7 years ago

html-utils (wiki): update documentation for version 0.10

  • Property svnwiki:tags set to html, web
  • Property svnwiki:title set to html-utils
File size: 10.5 KB
Line 
1== html-utils
2
3[[toc:]]
4
5=== Introduction
6
7{{html-utils}} is an extension which provides procedures to ease the generation of some frequently used [X]HTML structures.
8
9=== Author
10
11[[/users/mario-domenech-goulart|Mario Domenech Goulart]]
12
13=== Procedures
14
15==== {{itemize}}
16
17<procedure>(itemize items #!key list-id list-class quote-procedure)</procedure>
18
19Generates an HTML unordered list of {{items}}.  The following attributes may be used:
20
21* {{list-id}}: the value for the HTML {{id}} attribute for the list.
22* {{list-class}}: the value for the HTML {{class}} attribute for the list.
23* {{quote-procedure}}: an one-argument procedure to specify the quoting of attributes' values for tags.
24
25Examples:
26
27<enscript highlight=scheme>
28(itemize '(apple watermelon strawberry))
29</enscript>
30
31Produces:
32
33  "<ul><li>apple</li><li>watermelon</li><li>strawberry</li></ul>"
34
35
36<enscript highlight=scheme>
37(itemize '(apple watermelon strawberry) list-id: "my-list" list-class: "lists")
38</enscript>
39
40Produces:
41
42  "<ul id='my-list' class='lists'><li>apple</li><li>watermelon</li><li>strawberry</li></ul>"
43
44
45==== {{enumerate}}
46
47<procedure>(enumerate items #!key list-id list-class quote-procedure)</procedure>
48
49Generates an HTML ordered list of {{items}}.  See {{itemize}}.
50
51
52==== {{html-page}}
53
54<procedure>(html-page contents #!key css title (doctype "") (headers "") charset content-type literal-style? html-attribs body-attribs)</procedure>
55
56Generates an HTML page containing {{contents}} (a string). If contents starts with {{"<body"}} (case insensitive), {{html-page}} won't use the {{<body>}} tag to enclose {{contents}}. The following keywords arguments may be used to customize the page:
57
58* {{headers}}: a string containing additional headers to be inserted in the section delimited by the {{<head>}} tag. Default = {{""}}.
59
60* {{title}}: the title for the page (to be used in the {{<title>}} tag). Default = {{""}}.
61
62* {{css}}: may be either a path to a Cascading Style Sheet file, to be linked from the generated page (the default value is {{#f}}, so no CSS is used) or a list of paths to CSS files. If a list of paths is used, the elements which are also lists are read and inlined into the generated page. Example: {{css: '("css1.css" ("css2.css"))}}. In the example, {{css1.css}} would be linked from the generated page (using the link tag) and {{css2.css}} would be inlined into the generated page (e.g., {{html-page}} would read the {{css2.css}} file and inline its contents in the HTML code).
63
64* {{doctype}}: specifies the document type of the generated page. The default value is {{doctype:html-4.01-strict}}. The possible values are the ones available from the [[doctype]] egg.
65
66* {{charset}}: specifies the default charset to be used in the corresponding meta tag of the document. The default value is {{"UTF-8"}} (only when {{content-type}} is provided).
67
68* {{literal-style?}} (introduced in version 0.9): if {{#f}}, convert special characters in style code (CSS) to theyr equivalent HTML entities.  If non-{{#f}}, insert them verbatim.
69
70* {{content-type}} (introduced in version 0.9) and {{charset}} work together: if {{content-type}} is provided and {{charset}} is not provided, {{charset}} is assumed to be {{"UTF-8"}}; if {{charset}} is provided and {{content-type}} is not provided, {{content-type}} is assumed to be {{"text/html"}} (if [[/egg/html-tags|html-tags]]' {{generate-sxml?}} is {{#f}}) or {{"application/xhtml+xml"}} (if {{generate-sxml?}} is non-{{#f}}).
71
72* {{html-attribs}} (introduced in version 0.10): attributes to the {{html}} tag. The format is a list of lists {{(<attribute> <value>)}} ({{<attribute>}} is a symbol).  Example: {{(html-page "foo" html-attribs: '((lang "us")))}}.
73
74* {{body-attribs}} (introduced in version 0.10): attributes to the {{body}} tag. The format is a list of lists {{(<attribute> <value>)}} ({{<attribute>}} is a symbol).  Example: {{(html-page "foo" body-attribs: '((bgcolor "red")))}}.
75
76Examples:
77
78<enscript highlight=scheme>
79(html-page "hello")
80</enscript>
81
82Produces:
83
84  "<html><head></head><body>hello</body></html>"
85
86<enscript highlight=scheme>
87(html-page "hello" title: "hello")
88</enscript>
89
90Produces:
91
92  "<html><head><title>hello</title></head><body>hello</body></html>"
93
94
95<enscript highlight=scheme>
96(use doctype)
97(html-page "hello" title: "hello" doctype: xhtml-1.0-strict)
98</enscript>
99
100Produces:
101
102  "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\"><html><head><title>hello</title></head><body>hello</body></html>"
103
104
105<enscript highlight=scheme>
106(html-page "hello" headers: (<script> type: "text/javascript" src: "my-script.js"))
107</enscript>
108
109Produces:
110
111  "<html><head><script type='text/javascript' src='my-script.js'></script></head><body>hello</body></html>"   
112
113<enscript highlight=scheme>
114(use html-tags html-utils)
115(parameterize ((generate-sxml? #t))
116  (html-page "hello"
117             headers: (<script> type: "text/javascript"
118                                src: "my-script.js")))
119</enscript>
120
121Produces:
122
123  (html (head (script (@ (type "text/javascript") (src "my-script.js")))) (body "hello"))
124
125
126==== {{combo-box}}
127
128<procedure>(combo-box name options #!key default id first-empty onchange onkeyup disabled length multiple selectedindex size tabindex type class)</procedure>
129
130Generates an HTML combo box using {{<select>}} and {{<option>}} tags. The keyword parameters {{id}}, {{onchange}}, {{onkeyup}}, {{disabled}}, {{length}}, {{multiple}}, {{selectedindex}}, {{size}}, {{tabindex}}, {{type}} and {{class}} are passed to the {{<select>}} procedure (from [[/egg/html-tags|html-tags]]). {{default}} is the value from the list of options to be selected.  If {{first-empty}} is {{#t}}, the first option of the combo box will be empty.
131
132Example:
133
134<enscript highlight=scheme>
135(combo-box "test" '(#(1 1) #(2 2) #(3 3)) first-empty: #t default: 2)
136</enscript>
137
138Produces:
139
140 "<select name='test' id='test'><option></option><option value='1'>1</option><option value='2' selected>2</option><option value='3'>3</option></select>"
141
142
143
144==== {{hidden-input}}
145
146<procedure>(hidden-input name/list #!optional value id)</procedure>
147
148Generates an HTML hidden input field. {{name/list}} can be either a string representing the name attribute of the HTML input tag or an alist mapping names to values to be used by the corresponding input tags.  When {{name/list}} is a string, so representing the name of the input tag, the optional values VALUE and ID can be used to be represent the values of their corresponding HTML attributes.
149
150Examples:
151
152<enscript highlight=scheme>
153(hidden-input 'secret-var "secret-val")
154</enscript>
155
156Produces:
157
158  "<input type='hidden' name='secret-var' id='secret-var' value='secret-val'>"
159
160<enscript highlight=scheme>
161(hidden-input '((secret-var1 . "secret-val1") (secret-var2 . "secret-val2")))
162</enscript>
163
164Produces:
165
166  "<input type='hidden' id='secret-var1' name='secret-var1' value='secret-val1'><input type='hidden' id='secret-var2' name='secret-var2' value='secret-val2'>"
167
168
169==== {{text-input}}
170
171<procedure>(text-input name . args)</procedure>
172
173Generates an input text box. {{args}} are keyword arguments to be passed to {{<input>}} (from [[/egg/html-tags|html-tags]]).
174
175Examples:
176
177<enscript highlight=scheme>
178(text-input "foo" value: "bar")
179</enscript>
180
181Produces:
182
183  "<input type='text' name='foo' id='foo' value='bar'>"
184
185
186==== {{password-input}}
187
188<procedure>(password-input name . args)</procedure>
189
190The same as {{text-input}}, but for password inputs.
191
192
193==== {{submit-input}}
194
195<procedure>(submit-input . args)</procedure>
196
197Generates a submit widget.  {{args}} are keyword arguments to be passed to {{<input>}} (from [[/egg/html-tags|html-tags]]).
198
199<enscript highlight=scheme>
200 (submit-input value: "Send!")
201</enscript>
202
203Produces:
204
205  "<input type='submit' value='Send!'>"
206
207
208==== {{tabularize}}
209
210<procedure>(tabularize items #!key table-id table-class quote-procedure even-row-class odd-row-class header)</procedure>
211
212Generates an HTML table from {{items}} (a list of lists). The following keyword parameters may be used:
213
214* {{table-id}}: the value for the HTML {{id}} attribute for the table.
215* {{table-class}}: the value for the HTML {{class}} attribute for the table.
216* {{quote-procedure}}: an one-argument procedure to specify the quoting of attributes' values for tags.
217* {{even-row-class}}: the value for the HTML {{class}} attribute for even rows of the the table.
218* {{odd-row-class}}: the value for the HTML {{class}} attribute for odd rows of the the table.
219* {{header}}: a list of column names to be used as the table header (enclosed by the {{th}} tag).
220* {{thead/tbody}}: if {{#t}}, generates the table with {{<thead>}} and {{<tbody>}} tags.
221
222Examples:
223
224<enscript highlight=scheme>
225(tabularize '((1 2 3) (4 5 6)))
226</enscript>
227
228Produces:
229
230<nowiki>
231<pre>
232"&lt;table&gt;&lt;tr&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;2&lt;/td&gt;&lt;td&gt;3&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;4&lt;/td&gt;&lt;td&gt;5&lt;/td&gt;&lt;td&gt;6&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;"
233</pre>
234</nowiki>
235
236<enscript highlight=scheme>
237(tabularize '((1 2 3) (4 5 6)) table-id: "test" even-row-class: "yellow" odd-row-class: "blue")
238</enscript>
239
240Produces:
241
242<nowiki>
243<pre>
244"&lt;table id='test'&gt;&lt;tr class='yellow'&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;2&lt;/td&gt;&lt;td&gt;3&lt;/td&gt;&lt;/tr&gt;&lt;tr class='blue'&gt;&lt;td&gt;4&lt;/td&gt;&lt;td&gt;5&lt;/td&gt;&lt;td&gt;6&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;"
245</pre>
246</nowiki>
247
248
249=== License
250
251BSD
252
253
254=== Requirements
255
256[[/egg/html-tags|html-tags]]
257
258
259=== Version history
260
261==== Version 0.10
262
263* New keyword parameters for {{html-page}}: {{html-attribs}} and {{body-attribs}}.
264
265==== Version 0.9
266
267* Added {{literal-style?}} and {{content-type}} keyword parameters for {{html-page}}
268   
269* '''Warning''': the default behavior for inlined CSS ({{css}} keyword parameter for {{html-page}}) has changed.  Now the special HTML  characters are converted to their corresponding entities in non-SXML mode (i.e., when [[/egg/html-tags|html-tags]]' {{generate-sxml?}} is {{#f}} -- the default value).  This may break your page styles if you inline CSS via {{html-page}}'s {{css}} keyword parameter.  To get the old behavior, use {{literal-style?: #t}} for {{html-page}}.
270
271==== Version 0.8
272* Fixed order of elements in {{<head>}}: {{<meta http-equiv...>}} should be before {{<title>}} (reported by Sandra Snan)
273
274==== Version 0.7
275* Bugfix: {{password-input}} was not being exported
276
277==== Version 0.6
278* Added {{thead/tbody}} keyword parameter for {{tabularize}}
279
280==== Version 0.5
281* Added the {{password-input}} procedure and the {{header}} keyword parameter for {{tabularize}}
282
283==== Version 0.5
284* Added {{text-input}} and {{submit-input}}
285
286==== Version 0.1
287* Initial release
Note: See TracBrowser for help on using the repository browser.