13
13
<!-- = incidental or special damages arising in any way out of the use = -->
14
14
<!-- = of this software. = -->
15
15
<!-- ====================================================================== -->
16
<!-- = copyright (c) 1999-2007 - amaury darsch = -->
16
<!-- = copyright (c) 1999-2011 - amaury darsch = -->
17
17
<!-- ====================================================================== -->
19
19
<chapter service="wax" number="1">
20
20
<title>Web Application Extension Service</title>
23
This chapter covers the fundamental objects of the <afnix/> web
24
application extension (wax) service. This service provides the support
25
for low level HTTP transaction as well as high level XHTML page
26
generation and CGI scripts execution.
30
All <afnix/> web application extension objects are located in the
31
<code>afnix-wax</code> service module. This module must be loaded
32
prior any operation. Multiple calls to the module initialization
33
routine are harmless. The interpreter method <code>library</code>
34
loads a specific service module by name. When the module has been
35
loaded, the object are available in the <code>afnix:wax</code>
40
interp:library "afnix-wax"
23
This chapter covers the fundamental objects of the web application
24
extension (wax) service. This service provides the support
25
for low level HTTP transaction as well as high level XHTML page
26
generation and CGI scripts execution.
43
29
<!-- page service objects -->
45
31
<title>Page service objects</title>
48
The <code>XhtmlRoot</code> class is the primary interface to
49
generate <em>xhtml page</em>. The class is derived from the
50
<code>XmlRoot</code> class and the <code>Mime</code>object. for
51
this reason, creating a xhtml page is equivalent to add xml nodes
52
to the page. The xhtml version is assumed to be <em>1.1</em>.
34
The <code>XhtmlRoot</code> class is the primary interface to
35
generate <em>xhtml page</em>. The class is derived from the
36
<code>XmlRoot</code> class and the <code>Mime</code>object. for
37
this reason, creating a xhtml page is equivalent to add xml nodes
38
to the page. The xhtml version is assumed to be <em>1.1</em>.
55
41
<!-- page creation -->
57
43
<title>Page creation</title>
60
The <code>XhtmlRoot</code> constructor takes a string argument
61
which is the title page. When the root page is created, a
62
<em>head</em> and <em>body</em> nodes are automatically
63
created. Once created, it is possible to retrieve the head and
64
body nodes from the root node. The head and body nodes are part
65
of the <em>html</em> node which is automatically instantiated as
66
a <code>XhtmlHtml</code> object. The html node can always be
67
retrieved from the root node with the <code>get-child</code>
46
The <code>XhtmlRoot</code> constructor takes a string argument
47
which is the title page. When the root page is created, a
48
<em>head</em> and <em>body</em> nodes are automatically
49
created. Once created, it is possible to retrieve the head and
50
body nodes from the root node. The head and body nodes are part
51
of the <em>html</em> node which is automatically instantiated as
52
a <code>XhtmlHtml</code> object. The html node can always be
53
retrieved from the root node with the <code>get-child</code>
72
# create a new xhtml page
73
const page (afnix:wax:XhtmlRoot "AFNIX wax service")
75
const head (page:get-head)
77
const body (page:get-body)
58
# create a new xhtml page
59
const page (afnix:wax:XhtmlRoot "AFNIX wax service")
61
const head (page:get-head)
63
const body (page:get-body)
81
The head and body nodes are part of the <em>html</em> node which
82
is automatically instantiated as a <code>XhtmlHtml</code>
83
object. The html node can always be retrieved from the root node
84
with the <code>get-child</code> xml method. The root methods
85
<code>get-head</code> and <code>get-body</code> are convenient
86
methods that ease the page design by eliminating the references
67
The head and body nodes are part of the <em>html</em> node which
68
is automatically instantiated as a <code>XhtmlHtml</code>
69
object. The html node can always be retrieved from the root node
70
with the <code>get-child</code> xml method. The root methods
71
<code>get-head</code> and <code>get-body</code> are convenient
72
methods that ease the page design by eliminating the references
91
# create a new xhtml page
92
const page (afnix:wax:XhtmlRoot "AFNIX wax service")
94
const html (page:get-child "html")
96
const head (html:get-head)
98
const body (html:get-body)
77
# create a new xhtml page
78
const page (afnix:wax:XhtmlRoot "AFNIX wax service")
80
const html (page:get-child "html")
82
const head (html:get-head)
84
const body (html:get-body)
104
90
<title>Page header</title>
107
The <code>XhtmlHead</code> class is the xml node that handles
108
the xhtml head. The object is automatically created when calling
109
the <code>XhtmlRoot</code> constructor. During the construction
110
process, the head is automatically set with a title. Once
111
created, the head can be filled with meta information and
112
styles. The <code>add-meta</code> method is designed to add meta
113
information, while the <code>add-style</code> add a link node
114
with a style reference to the head.
119
head:add-meta "copyright" "© 2000"
121
head:add-style "/style.css"
125
The <code>add-meta</code> method adds a <code>XhtmlMeta</code>
126
object which is a xml tag node. The first argument is the meta
127
descriptor while the second argument is the meta content. Note
128
that the <code>add-meta</code> method can be simulated by
129
calling the <code>XhtmlMeta</code> constructor and then adding
130
the node to the head node.
135
const node (afnix:wax:XhtmlMeta "copyright" "© 2000")
136
# add the node to the head
141
The <code>add-style</code> method adds a <code>XhtmlStyle</code>
142
object which is a xml tag node. The string argument is the url
143
style sheet path which gets automatically transformed to the
144
form <em>@import(url)</em>. Note that the <code>add-style</code>
145
method can be simulated by calling the <code>XhtmlStyle</code>
146
constructor and then adding the node to the head node.
150
# create a style node
151
const node (afnix:wax:XhtmlStyle "/style.css")
152
# add the node to the head
93
The <code>XhtmlHead</code> class is the xml node that handles
94
the xhtml head. The object is automatically created when calling
95
the <code>XhtmlRoot</code> constructor. During the construction
96
process, the head is automatically set with a title. Once
97
created, the head can be filled with meta information and
98
styles. The <code>add-meta</code> method is designed to add meta
99
information, while the <code>add-style</code> add a link node
100
with a style reference to the head.
105
head:add-meta "copyright" "(c) 2000"
107
head:add-style "/style.css"
111
The <code>add-meta</code> method adds a <code>XhtmlMeta</code>
112
object which is a xml tag node. The first argument is the meta
113
descriptor while the second argument is the meta content. Note
114
that the <code>add-meta</code> method can be simulated by
115
calling the <code>XhtmlMeta</code> constructor and then adding
116
the node to the head node.
121
const node (afnix:wax:XhtmlMeta "copyright" "(c) 2011")
122
# add the node to the head
127
The <code>add-style</code> method adds a <code>XhtmlStyle</code>
128
object which is a xml tag node. The string argument is the url
129
style sheet path which gets automatically transformed to the
130
form <em>@import(url)</em>. Note that the <code>add-style</code>
131
method can be simulated by calling the <code>XhtmlStyle</code>
132
constructor and then adding the node to the head node.
136
# create a style node
137
const node (afnix:wax:XhtmlStyle "/style.css")
138
# add the node to the head
159
145
<title>Page body</title>
162
The <code>XhtmlBody</code> class is the xml node that handles
163
the xhtml body. The object is automatically created when calling
164
the <code>XhtmlRoot</code> constructor. Once created, the body
165
node can be filled with any valid xhtml node. Since the node are
166
initially xml tag node, it is always possible to create a tag by
167
name and set the attributes and child nodes manually.
148
The <code>XhtmlBody</code> class is the xml node that handles
149
the xhtml body. The object is automatically created when calling
150
the <code>XhtmlRoot</code> constructor. Once created, the body
151
node can be filled with any valid xhtml node. Since the node are
152
initially xml tag node, it is always possible to create a tag by
153
name and set the attributes and child nodes manually.
171
# create a new xhtml page
172
const page (afnix:wax:XhtmlRoot "AFNIX wax service")
174
const body (page:get-body)
157
# create a new xhtml page
158
const page (afnix:wax:XhtmlRoot "AFNIX wax service")
160
const body (page:get-body)
182
168
<title>Page emission</title>
185
Since the <code>XhtmlRoot</code> object is a xml root node, the
186
node can be used to write the complete hierarchy. The xml node
187
node provides the <code>write</code> method that write a xml
188
tree into a buffer of an output stream.
171
Since the <code>XhtmlRoot</code> object is a xml root node, the
172
node can be used to write the complete hierarchy. The xml node
173
node provides the <code>write</code> method that write a xml
174
tree into a buffer of an output stream.
192
# create a new xhtml page
193
const page (afnix:wax:XhtmlRoot "AFNIX wax service")
194
# write to the output stream
178
# create a new xhtml page
179
const page (afnix:wax:XhtmlRoot "AFNIX wax service")
180
# write to the output stream
199
Another mechanism for writing the page is to use the fact that
200
the <code>XhtmlRoot</code> class implements also the
201
<code>Mime</code> interface. With this in mind, the
202
<code>XhtmlRoot</code> can be used within the
203
<code>HttpReply</code>. This method is particularly useful when
204
writing automated page generation, such like CGI scripts.
185
Another mechanism for writing the page is to use the fact that
186
the <code>XhtmlRoot</code> class implements also the
187
<code>Mime</code> interface. With this in mind, the
188
<code>XhtmlRoot</code> can be used within the
189
<code>HttpReply</code>. This method is particularly useful when
190
writing automated page generation, such like CGI scripts.
208
# create a new xhtml page
209
const page (afnix:wax:XhtmlRoot "AFNIX wax service")
210
# create an http reply object
211
const reply (afnix:wax:HttpReply)
212
# write the page as a mime object
213
reply:add-buffer page
214
# write the result to the output
194
# create a new xhtml page
195
const page (afnix:wax:XhtmlRoot "AFNIX wax service")
196
# create an http reply object
197
const reply (afnix:wax:HttpReply)
198
# write the page as a mime object
199
reply:add-buffer page
200
# write the result to the output
222
208
<title>Page design objects</title>
225
The <em>wax service module</em> is designed to provide several
226
object that ease the task of creating a xhtml page. Such objects
227
range from comment to table. Most of the time, the construction is
228
simple the resulting node only need to be added to the page
229
tree. When it comes to add text, the problem is becoming more
230
subtle and is discussed later in this section.
211
The <em>wax service module</em> is designed to provide several
212
object that ease the task of creating a xhtml page. Such objects
213
range from comment to table. Most of the time, the construction is
214
simple the resulting node only need to be added to the page
215
tree. When it comes to add text, the problem is becoming more
216
subtle and is discussed later in this section.
233
219
<!-- xhtml comment -->
235
221
<title>Comment node</title>
238
Adding a comment is done with the <code>XmlComment</code> class
239
which take the comment string in the constructor. Once created,
240
the comment node can be added to the tree.
224
Adding a comment is done with the <code>XmlComment</code> class
225
which take the comment string in the constructor. Once created,
226
the comment node can be added to the tree.
244
# add a comment to the body node
245
body:add-child (afnix:xml:XmlComment "this is a comment")
230
# add a comment to the body node
231
body:add-child (afnix:xml:XmlComment "this is a comment")
251
237
<title>Node style class</title>
254
When the xhtml page is combined with the cascaded style sheet
255
(CSS), the xhtml node tag often uses a <em>class</em> name to
256
refer to a particular style. The <em>class style</em> is just a
257
node attribute which can be set with the
258
<code>add-attribute</code> method. However, most of the time,
259
the library provides object which have the style as the first
260
argument in the constructor. For example, the
261
<code>XhtmlDiv</code> constructor take 0 or one argument. With
262
one argument, the string argument is used as the style attribute.
240
When the xhtml page is combined with the cascaded style sheet
241
(CSS), the xhtml node tag often uses a <em>class</em> name to
242
refer to a particular style. The <em>class style</em> is just a
243
node attribute which can be set with the
244
<code>add-attribute</code> method. However, most of the time,
245
the library provides object which have the style as the first
246
argument in the constructor. For example, the
247
<code>XhtmlDiv</code> constructor take 0 or one argument. With
248
one argument, the string argument is used as the style attribute.
266
# create a xhtml div with a class attribute
267
const div (afnix:wax:XhtmlDiv "nice")
268
# create a xhtml div and set the class manually
269
const div (afnix:wax:XhtmlDiv)
270
div:set-attribute "class" "nice"
252
# create a xhtml div with a class attribute
253
const div (afnix:wax:XhtmlDiv "nice")
254
# create a xhtml div and set the class manually
255
const div (afnix:wax:XhtmlDiv)
256
div:set-attribute "class" "nice"
276
262
<title>Adding text paragraph</title>
279
Adding text to a page is not a trivial task when it comes to deal
280
with text style. By default, a piece of text is stored in the
281
<code>XmlText</code> node. Using this node is easy. However, in
282
a programming context, its use can become heavy. For this reason,
283
all xml nodes provide the <code>parse</code> method which can be
284
used to add a xml tree to the calling node. When it comes to add
285
text that includes rendering tag, this method is quite handy.
265
Adding text to a page is not a trivial task when it comes to deal
266
with text style. By default, a piece of text is stored in the
267
<code>XmlText</code> node. Using this node is easy. However, in
268
a programming context, its use can become heavy. For this reason,
269
all xml nodes provide the <code>parse</code> method which can be
270
used to add a xml tree to the calling node. When it comes to add
271
text that includes rendering tag, this method is quite handy.
289
# add a text with some piece in italic
290
node:parse "this is a <i>simple</i> method"
275
# add a text with some piece in italic
276
node:parse "this is a <i>simple</i> method"
294
The <code>XhtmlPara</code> node is the preferred node for
295
adding text to a xhtml page. The node takes optionally the style
296
name in the constructor. A boolean flag can also be used to
297
create an empty paragraph node.
280
The <code>XhtmlPara</code> node is the preferred node for
281
adding text to a xhtml page. The node takes optionally the style
282
name in the constructor. A boolean flag can also be used to
283
create an empty paragraph node.
301
# create a paragraph node with a style
302
const p (afnix:wax:XhtmlPara "title")
304
p:parse "the paragraph text"
287
# create a paragraph node with a style
288
const p (afnix:wax:XhtmlPara "title")
290
p:parse "the paragraph text"
310
296
<title>Adding reference</title>
313
Adding reference or hyperlink to a page is achieved with the
314
<code>XhtmlRef</code> class. Most of the time, the object is
315
built with a uri and a text. when the node has been created, the
316
node can be added to the page tree.
299
Adding reference or hyperlink to a page is achieved with the
300
<code>XhtmlRef</code> class. Most of the time, the object is
301
built with a uri and a text. when the node has been created, the
302
node can be added to the page tree.
321
const node (afnix:wax:XhtmlRef "http://www.afnix.org" "afnix")
322
# add the node in a paragraph
307
const node (afnix:wax:XhtmlRef "http://www.afnix.org" "afnix")
308
# add the node in a paragraph
329
315
<title>Formatting elements</title>
332
The <code>XhtmlDiv</code> and <code>XhtmlHr</code> classes
333
are the basic formatting xhtml elements. The
334
<code>XhtmlDiv</code> is a grouping element and the
335
<code>XhtmlHr</code> is a simple horizontal ruler element. Both
336
classes take 0 or one argument which is the style name.
318
The <code>XhtmlDiv</code> and <code>XhtmlHr</code> classes
319
are the basic formatting xhtml elements. The
320
<code>XhtmlDiv</code> is a grouping element and the
321
<code>XhtmlHr</code> is a simple horizontal ruler element. Both
322
classes take 0 or one argument which is the style name.
340
# create a div element
341
const div (afnix:wax:XhtmlDiv "menu")
342
# create a ruler element
343
const hr (afnix:wax:XhtmlHr)
326
# create a div element
327
const div (afnix:wax:XhtmlDiv "menu")
328
# create a ruler element
329
const hr (afnix:wax:XhtmlHr)
350
336
<title>Managing table</title>
353
The <em>wax service module</em> provides an extensive support of
354
he xhtml table element. There are basically two strategies for
355
creating a table. One is to use the html elements or the other is
356
to use a print table object and automatically feed the xhtml
357
table. The first method provides a better control while the second
358
one is easier to use.
339
The <em>wax service module</em> provides an extensive support of
340
he xhtml table element. There are basically two strategies for
341
creating a table. One is to use the html elements or the other is
342
to use a print table object and automatically feed the xhtml
343
table. The first method provides a better control while the second
344
one is easier to use.
361
347
<!-- xhtml table element -->
363
349
<title>The table element</title>
366
The <code>XhtmlTable</code> class is the class that manages
367
xhtml table. As usual, a default style name can be specified in
368
the constructor. Eventually, a default table row and table data
369
default style can also be specified. Such default value are used
370
when creating a new row with the <code>new-row</code> method.
352
The <code>XhtmlTable</code> class is the class that manages
353
xhtml table. As usual, a default style name can be specified in
354
the constructor. Eventually, a default table row and table data
355
default style can also be specified. Such default value are used
356
when creating a new row with the <code>new-row</code> method.
374
# create a table element with a default tr and th/td style
375
const tbl (afnix:wax:XhtmlTable "text" "text" "text")
376
# get a new row with a default style
377
const tr (tbl:new-row)
360
# create a table element with a default tr and th/td style
361
const tbl (afnix:wax:XhtmlTable "text" "text" "text")
362
# get a new row with a default style
363
const tr (tbl:new-row)
381
In the previous example, a table is created with a default style
382
for the table row. When a new row is created, the default style
383
is used for that row. If there is no default style, the row is
384
created without a style. Note that the <code>new-row</code>
385
method takes also a style argument that overwrites the default
367
In the previous example, a table is created with a default style
368
for the table row. When a new row is created, the default style
369
is used for that row. If there is no default style, the row is
370
created without a style. Note that the <code>new-row</code>
371
method takes also a style argument that overwrites the default
392
378
<title>Building the table</title>
395
A table is built by adding row and data element into the
396
rows. A row is created with the <code>new-row</code> method or
397
the object can be constructed directly and added to the node
398
with the <code>add-child</code> method. The <code>XhtmlTr</code>
399
class is the table row class.
403
# get a new row with a default style
404
trans tr (tbl:new-row)
405
# create a row directly
406
trans tr (afnix:wax:XhtmlTr "text")
410
When a row has been created, the data can be added to the
411
row. Normally, the <code>new-data</code> method is used to
412
create a new table data element. If a default style is defined
413
in the table row, the table data element is built with that
414
style. The <code>new-head</code> method can also be used to
415
create table header element. Again, if a default table header
416
style exists in the table row, the element is built with that
417
style. The <code>XhtmlTd</code> class is the table data class
418
and the <code>XhtmlTh</code> class is the table header class.
422
# get a new data element
423
trans td (tr:new-data)
424
# create new head element
425
trans th (tr:new-head)
429
When the table data node has been created, the
430
<code>parse</code> method or the <code>add-child</code> method
431
can be called to add other nodes. another method for building
432
the table is to use the <code>add-table</code> method which uses
433
a print table object. In such case, the table rows and data
434
elements are automatically added in the table.
381
A table is built by adding row and data element into the
382
rows. A row is created with the <code>new-row</code> method or
383
the object can be constructed directly and added to the node
384
with the <code>add-child</code> method. The <code>XhtmlTr</code>
385
class is the table row class.
389
# get a new row with a default style
390
trans tr (tbl:new-row)
391
# create a row directly
392
trans tr (afnix:wax:XhtmlTr "text")
396
When a row has been created, the data can be added to the
397
row. Normally, the <code>new-data</code> method is used to
398
create a new table data element. If a default style is defined
399
in the table row, the table data element is built with that
400
style. The <code>new-head</code> method can also be used to
401
create table header element. Again, if a default table header
402
style exists in the table row, the element is built with that
403
style. The <code>XhtmlTd</code> class is the table data class
404
and the <code>XhtmlTh</code> class is the table header class.
408
# get a new data element
409
trans td (tr:new-data)
410
# create new head element
411
trans th (tr:new-head)
415
When the table data node has been created, the
416
<code>parse</code> method or the <code>add-child</code> method
417
can be called to add other nodes. another method for building
418
the table is to use the <code>add-table</code> method which uses
419
a print table object. In such case, the table rows and data
420
elements are automatically added in the table.
440
426
<title>The table structure</title>
443
The table can be designed directly with table rows with table
444
headers and table data elements. Another method, which is more
445
structured is to use the table head, table body and table footer
446
elements. The <code>XhtmlThead</code> class is the table head
447
element class. The <code>XhtmlTbody</code> class is the table body
448
element class. The <code>XhtmlTfoot</code> class is the table footer
449
element class. These classes behaves exactly like the
450
<code>XhtmlTable</code> and are in fact all derived from the
451
<code>XhtmlTelem</code> class.
455
# create a xhtml table
456
const table (afnix:wax:XhtmlTable "text")
457
# create a table body
458
const tbody (afnix:wax:XhtmlTable "text" "text" "text")
459
# add a print tbl in the body
461
# add the body to the table
466
A table caption node can also be set with the
467
<code>set-caption</code> method. The method simply creates a
468
<code>XhtmlCaption</code> node and adds it to the table. The
469
caption text is part of the method call which is used by the
470
caption node constructor. It is also possible to create the
471
caption node by calling the <code>XhtmlCaption</code>
472
constructor and adding it to the table with he
473
<code>add-child</code> method.
477
# create a xhtml table
478
const table (afnix:wax:XhtmlTable "text")
479
# set a table caption
480
table:set-caption "the afnix table system"
484
The table structure can also be defined with the
485
<code>XhtmlCgr</code> class which corresponds to the xhtml column
486
group element. The column group element is designed to support
487
the <em>col</em> element that formats the table column.
492
const table (afnix:wax:XhtmlTable "text")
493
# set the table with to 100%
494
table:add-attribute "width" "100%"
495
# create a column group
496
table:add-child (const cgr (afnix:wax:XhtmlCgr))
497
# add a column with 30% width
498
cgr:add-child (afnix:wax:XhtmlCol "30%")
499
# add a column with 70% width
500
cgr:add-child (afnix:wax:XhtmlCol "70%")
429
The table can be designed directly with table rows with table
430
headers and table data elements. Another method, which is more
431
structured is to use the table head, table body and table footer
432
elements. The <code>XhtmlThead</code> class is the table head
433
element class. The <code>XhtmlTbody</code> class is the table body
434
element class. The <code>XhtmlTfoot</code> class is the table footer
435
element class. These classes behaves exactly like the
436
<code>XhtmlTable</code> and are in fact all derived from the
437
<code>XhtmlTelem</code> class.
441
# create a xhtml table
442
const table (afnix:wax:XhtmlTable "text")
443
# create a table body
444
const tbody (afnix:wax:XhtmlTable "text" "text" "text")
445
# add a print tbl in the body
447
# add the body to the table
452
A table caption node can also be set with the
453
<code>set-caption</code> method. The method simply creates a
454
<code>XhtmlCaption</code> node and adds it to the table. The
455
caption text is part of the method call which is used by the
456
caption node constructor. It is also possible to create the
457
caption node by calling the <code>XhtmlCaption</code>
458
constructor and adding it to the table with he
459
<code>add-child</code> method.
463
# create a xhtml table
464
const table (afnix:wax:XhtmlTable "text")
465
# set a table caption
466
table:set-caption "the afnix table system"
470
The table structure can also be defined with the
471
<code>XhtmlCgr</code> class which corresponds to the xhtml column
472
group element. The column group element is designed to support
473
the <em>col</em> element that formats the table column.
478
const table (afnix:wax:XhtmlTable "text")
479
# set the table with to 100%
480
table:add-attribute "width" "100%"
481
# create a column group
482
table:add-child (const xcgr (afnix:wax:XhtmlCgr))
483
# add a column with 30% width
484
cgr:add-child (afnix:wax:XhtmlCol "30%")
485
# add a column with 70% width
486
cgr:add-child (afnix:wax:XhtmlCol "70%")
added
removed
src/srv/wax/doc/chapter-1.xml
