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

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

html-utils (wiki): general note on generate-sxml? and specific note on strings/SXML mode for the headers keyword parameter for html-page (thanks to Hugo Arregui for bringing my attention to this).

  • Property svnwiki:tags set to html, web
  • Property svnwiki:title set to html-utils
File size: 11.0 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 [SX]HTML structures.
8
9{{html-utils}} is based on [[/egg/html-tags|html-tags]], so it can generate strings or SXML code.  The html-tags' {{generate-sxml?}} parameter (yields a boolean) specifies whether html-utils should generate strings or SXML code.
10
11Example:
12
13  $ csi -n
14  #;1> (use html-tags html-utils)
15  #;2> (generate-sxml?)
16  #f
17  #;3> (itemize '(1 2 3))
18  "<ul><li>1</li><li>2</li><li>3</li></ul>"
19  #;4> (generate-sxml? #t)
20  #t
21  #;5> (itemize '(1 2 3))
22  (ul (li 1) (li 2) (li 3))
23
24
25=== Author
26
27[[/users/mario-domenech-goulart|Mario Domenech Goulart]]
28
29=== Procedures
30
31==== {{itemize}}
32
33<procedure>(itemize items #!key list-id list-class quote-procedure)</procedure>
34
35Generates an HTML unordered list of {{items}}.  The following attributes may be used:
36
37* {{list-id}}: the value for the HTML {{id}} attribute for the list.
38* {{list-class}}: the value for the HTML {{class}} attribute for the list.
39* {{quote-procedure}}: an one-argument procedure to specify the quoting of attributes' values for tags.
40
41Examples:
42
43<enscript highlight=scheme>
44(itemize '(apple watermelon strawberry))
45</enscript>
46
47Produces:
48
49  "<ul><li>apple</li><li>watermelon</li><li>strawberry</li></ul>"
50
51
52<enscript highlight=scheme>
53(itemize '(apple watermelon strawberry) list-id: "my-list" list-class: "lists")
54</enscript>
55
56Produces:
57
58  "<ul id='my-list' class='lists'><li>apple</li><li>watermelon</li><li>strawberry</li></ul>"
59
60
61==== {{enumerate}}
62
63<procedure>(enumerate items #!key list-id list-class quote-procedure)</procedure>
64
65Generates an HTML ordered list of {{items}}.  See {{itemize}}.
66
67
68==== {{html-page}}
69
70<procedure>(html-page contents #!key css title (doctype "") (headers "") charset content-type literal-style? html-attribs body-attribs)</procedure>
71
72Generates 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:
73
74* {{headers}}: a string (when not in SXML mode) or an SXML form (when in SXML mode) containing additional headers to be inserted in the section delimited by the {{<head>}} tag. Default = {{""}}.
75
76* {{title}}: the title for the page (to be used in the {{<title>}} tag). Default = {{""}}.
77
78* {{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).
79
80* {{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.
81
82* {{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).
83
84* {{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.
85
86* {{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}}).
87
88* {{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")))}}.
89
90* {{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")))}}.
91
92Examples:
93
94<enscript highlight=scheme>
95(html-page "hello")
96</enscript>
97
98Produces:
99
100  "<html><head></head><body>hello</body></html>"
101
102<enscript highlight=scheme>
103(html-page "hello" title: "hello")
104</enscript>
105
106Produces:
107
108  "<html><head><title>hello</title></head><body>hello</body></html>"
109
110
111<enscript highlight=scheme>
112(use doctype)
113(html-page "hello" title: "hello" doctype: xhtml-1.0-strict)
114</enscript>
115
116Produces:
117
118  "<!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>"
119
120
121<enscript highlight=scheme>
122(html-page "hello" headers: (<script> type: "text/javascript" src: "my-script.js"))
123</enscript>
124
125Produces:
126
127  "<html><head><script type='text/javascript' src='my-script.js'></script></head><body>hello</body></html>"   
128
129<enscript highlight=scheme>
130(use html-tags html-utils)
131(parameterize ((generate-sxml? #t))
132  (html-page "hello"
133             headers: (<script> type: "text/javascript"
134                                src: "my-script.js")))
135</enscript>
136
137Produces:
138
139  (html (head (script (@ (type "text/javascript") (src "my-script.js")))) (body "hello"))
140
141
142==== {{combo-box}}
143
144<procedure>(combo-box name options #!key default id first-empty onchange onkeyup disabled length multiple selectedindex size tabindex type class)</procedure>
145
146Generates 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.
147
148Example:
149
150<enscript highlight=scheme>
151(combo-box "test" '(#(1 1) #(2 2) #(3 3)) first-empty: #t default: 2)
152</enscript>
153
154Produces:
155
156 "<select name='test' id='test'><option></option><option value='1'>1</option><option value='2' selected>2</option><option value='3'>3</option></select>"
157
158
159
160==== {{hidden-input}}
161
162<procedure>(hidden-input name/list #!optional value id)</procedure>
163
164Generates 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.
165
166Examples:
167
168<enscript highlight=scheme>
169(hidden-input 'secret-var "secret-val")
170</enscript>
171
172Produces:
173
174  "<input type='hidden' name='secret-var' id='secret-var' value='secret-val'>"
175
176<enscript highlight=scheme>
177(hidden-input '((secret-var1 . "secret-val1") (secret-var2 . "secret-val2")))
178</enscript>
179
180Produces:
181
182  "<input type='hidden' id='secret-var1' name='secret-var1' value='secret-val1'><input type='hidden' id='secret-var2' name='secret-var2' value='secret-val2'>"
183
184
185==== {{text-input}}
186
187<procedure>(text-input name . args)</procedure>
188
189Generates an input text box. {{args}} are keyword arguments to be passed to {{<input>}} (from [[/egg/html-tags|html-tags]]).
190
191Examples:
192
193<enscript highlight=scheme>
194(text-input "foo" value: "bar")
195</enscript>
196
197Produces:
198
199  "<input type='text' name='foo' id='foo' value='bar'>"
200
201
202==== {{password-input}}
203
204<procedure>(password-input name . args)</procedure>
205
206The same as {{text-input}}, but for password inputs.
207
208
209==== {{submit-input}}
210
211<procedure>(submit-input . args)</procedure>
212
213Generates a submit widget.  {{args}} are keyword arguments to be passed to {{<input>}} (from [[/egg/html-tags|html-tags]]).
214
215<enscript highlight=scheme>
216 (submit-input value: "Send!")
217</enscript>
218
219Produces:
220
221  "<input type='submit' value='Send!'>"
222
223
224==== {{tabularize}}
225
226<procedure>(tabularize items #!key table-id table-class quote-procedure even-row-class odd-row-class header)</procedure>
227
228Generates an HTML table from {{items}} (a list of lists). The following keyword parameters may be used:
229
230* {{table-id}}: the value for the HTML {{id}} attribute for the table.
231* {{table-class}}: the value for the HTML {{class}} attribute for the table.
232* {{quote-procedure}}: an one-argument procedure to specify the quoting of attributes' values for tags.
233* {{even-row-class}}: the value for the HTML {{class}} attribute for even rows of the the table.
234* {{odd-row-class}}: the value for the HTML {{class}} attribute for odd rows of the the table.
235* {{header}}: a list of column names to be used as the table header (enclosed by the {{th}} tag).
236* {{thead/tbody}}: if {{#t}}, generates the table with {{<thead>}} and {{<tbody>}} tags.
237
238Examples:
239
240<enscript highlight=scheme>
241(tabularize '((1 2 3) (4 5 6)))
242</enscript>
243
244Produces:
245
246<nowiki>
247<pre>
248"&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;"
249</pre>
250</nowiki>
251
252<enscript highlight=scheme>
253(tabularize '((1 2 3) (4 5 6)) table-id: "test" even-row-class: "yellow" odd-row-class: "blue")
254</enscript>
255
256Produces:
257
258<nowiki>
259<pre>
260"&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;"
261</pre>
262</nowiki>
263
264
265=== License
266
267BSD
268
269
270=== Requirements
271
272[[/egg/html-tags|html-tags]]
273
274
275=== Version history
276
277==== Version 0.10
278
279* New keyword parameters for {{html-page}}: {{html-attribs}} and {{body-attribs}}.
280
281==== Version 0.9
282
283* Added {{literal-style?}} and {{content-type}} keyword parameters for {{html-page}}
284   
285* '''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}}.
286
287==== Version 0.8
288* Fixed order of elements in {{<head>}}: {{<meta http-equiv...>}} should be before {{<title>}} (reported by Sandra Snan)
289
290==== Version 0.7
291* Bugfix: {{password-input}} was not being exported
292
293==== Version 0.6
294* Added {{thead/tbody}} keyword parameter for {{tabularize}}
295
296==== Version 0.5
297* Added the {{password-input}} procedure and the {{header}} keyword parameter for {{tabularize}}
298
299==== Version 0.5
300* Added {{text-input}} and {{submit-input}}
301
302==== Version 0.1
303* Initial release
Note: See TracBrowser for help on using the repository browser.