source: project/wiki/eggref/3/web-scheme @ 13621

Last change on this file since 13621 was 13621, checked in by sjamaan, 11 years ago

Move old chicken 3 eggs over to eggref/3

File size: 12.3 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== Introduction
5
6Web-scheme is a Chicken Scheme extension which implements a web programming language based on Scheme. It can be used with the [[spiffy]] web server to generate programmable dynamic web pages.
7
8Web-scheme basically implements all HTML tags as Scheme procedures (see note below), so you can format your pages just like you'd do with HTML, but using the Scheme syntax and having the possibility of using the Chicken Scheme's features for programming. Additionaly, it provides some (hopefuly) useful procedures and macros to ease the formatting of web pages. A special case regarding to HTML tags as Scheme procedures is HTML attributes which don't take a value, e.g., the multiple attribute, which can be used, for exemple, in the {{<select>}} tag. In this special case, web-scheme requires a boolean (usually {{#t}}) as a value to the attribute.
9
10The procedures defined by web-scheme to generate HTML tags are named according to tag names. So, the procedure which generates the {{blockquote}} tag is called {{blockquote}}.  There are exceptions, however: {{ws:select}} and {{ws:map}} not to clash with common Scheme names.
11
12You can either use web-scheme as a programming language for generating dynamic web pages with [[spiffy]] or for generating static HTML pages which can be used with any other web server.
13
14From version 1.50, [[spiffy]] interprets files with .ws suffix as web-scheme files. So, to make dynamic web pages with web-scheme, just use it as if you were making a regular Scheme program. From version 3.0, [[spiffy]] uses web-scheme as a special handler (see http://chicken.wiki.br/spiffy#web-scheme-handler for further details).
15
16The Emacs-Lisp file [[http://chicken.wiki.br/web-scheme-data/web-scheme.el|web-scheme.el]] provides a few helpful commands to simplify escaping quotes and slashes (i.e., inside pre tags).
17
18Besides providing HTML tags as procedures, web-scheme provides the procedures, macros, variables and parameters you can see on the next section.
19
20== Author
21
22[[Mario Domenech Goulart]]
23
24
25== Requirements
26
27[[spiffy]], [[doctype]]
28
29
30== Procedures, macros and parameters
31
32=== General
33
34==== ws:page
35
36    '''procedure:''' (ws:page CONTENTS #!key ADDITIONAL-HEADERS PAGE-TITLE DOCTYPE CSS-FILE CHARSET BODY-ATTRIBS)
37
38Creates an HTML page containing CONTENTS (a string). Keywords arguments may be used to customize the page.
39
40ADDITIONAL-HEADERS is a string containg additional headers to be inserted in the (header ...) tag (default = "").
41
42PAGE-TITLE is the title of the generated page (to be used in the (title ...)) tag (default = {{""}}).
43
44CSS-FILE may be either a path to a Cascading Style Sheet file, to be linked fom 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-file: '("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., web-scheme would read the {{css2.css}} file and inline its contents in the HTML code).
45
46DOCTYPE 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.
47
48CHARSET specifies the default charset to be used in the corresponding meta tag of the document. The default value is iso-8859-1.
49
50BODY-ATTRIBS is a list of attributes and their values to be used in the body tag.
51
52
53==== ws:make-table
54
55   '''procedure:''' (ws:make-table TABLE . ARGS)
56
57Creates an HTML table. TABLE is a list of lists. Each sub-list element from TABLE is representative of a table row, with the requirement that each row element have a string representation when {{->string}} is automatically applied to it.  ARGS are keyword arguments. ws:make-table understands the following arguments:
58
59; row-attribs : a list of row attributes (e.g., {{'(bgcolor "yellow" align "center"))}}.
60
61; cell-attribs : a list of cell attributes (e.g., {{'(width "30" valign "middle"))}}.
62
63; line-attribs : a one-argument procedure which takes a line number (corresponding to the current table row being processed) and returns a list of row attributes.
64
65; line-format : a one-argument procedure which takes a line number (corresponding to the current table row being processed) and returns a procedure to be applied to all cells of the ''nth'' table line (where ''n'' is the line number used as an argument for the given procedure).
66
67==== ws:table-colorizer
68
69   '''procedure:''' (ws:table-colorizer ID-EVEN ID-ODD)
70
71Returns a procedure to colorize table lines. To be used by the {{line-format}} keyword argument of {{ws:make-table}}. ID-EVEN and ID-ODD are values for the id attribute of div tags used to format the lines.
72
73
74==== ws:itemize
75
76    '''procedure:''' (ws:itemize ITEMS . ARGS)
77
78Creates an unordered list of ITEMS. ITEMS is a list of items having a string representation ({{->string}} is applied). ARGS are keyword arguments. {{ws:itemize}} understands the following arguments:
79
80; list-attribs : a list of attributes for the list of items (e.g., {{'(type "circle")}}).
81
82; items-attribs : a list of attributes for each item from the list.
83
84
85==== ws:enumerate
86
87    '''procedure:''' (ws:enumerate ITEMS . ARGS)
88
89Creates an ordered list of ITEMS. ITEMS is a list of items having a string representation ({{->string}} is applied). ARGS are keyword arguments. {{ws:enumerate}} understands the following arguments:
90
91; list-attribs : a list of attributes for the list of items (e.g., {{'(type "circle")}}).
92
93; items-attribs : a list of attributes for each item from the list.
94
95
96==== ws:mailto
97
98    '''procedure:''' (ws:mailto ADDRESS #!optional OBFUSCATION-FUNCTION)
99
100Creates a link to an e-mail address ADDRESS. The optional parameter OBFUSCATION-FUNCTION is a one-argument procedure which formats the e-mail address in order to obfuscate it (against spam).
101
102The following obfuscation functions are available:
103
104; {{ws:email-at-dot-obfuscation}} : transforms {{user@address.somewhere}} into {{user at address dot somewhere}}.
105
106; {{ws:email-paren-uline-obfuscation}} : transforms {{user@address.somewhere}} into {{user()address_somewhere}}.
107
108
109==== ws:blank
110
111    '''variable: ''' ws:blank
112
113Produces an HTML whitespace.
114
115
116==== ws:vspace
117
118    '''procedure:''' (ws:vspace #!optional UNITS)
119
120Generates an HTML vertical space by creating empty paragraphs. UNITS determines the length of the space.
121
122
123==== ws:hspace
124
125    '''procedure:''' (ws:hspace #!optional UNITS)
126
127Generates an HTML horizontal space by inserting whitespaces. UNITS determines the length of the space.
128
129==== ws:load
130
131    '''procedure:''' (ws:load FILE)
132
133Loads FILE. FILE can be a path relative to the current working directory (uses spiffy's ({{current-workdir}} and {{load}}).
134
135==== ws:text-only-made-with
136
137    '''procedure:''' (ws:text-only-made-with)
138
139Generates a text only ''made with web-scheme'' logo.
140
141
142==== ws:made-with
143
144    '''procedure:''' (ws:made-with #!optional logo)
145
146Generates a graphical ''made with web-scheme'' logo. if LOGO (an image file) is not provided, the one at http://chicken.wiki.br/web-scheme-data/web-scheme.png is used.
147
148==== ws:check-html-syntax
149
150    '''parameter:''' ws:check-html-syntax
151
152If set to {{#t}} web-scheme checks if the attributes used for HTML tags are ok and generates a commented warning on the HTML page.  Default is {{#f}}.
153
154==== ws:human-readable-html
155
156    '''parameter:''' ws:human-readable-html
157
158If set to {{#t}}, web-scheme produces HTML code which is (hopefully) readable by humans. If {{#f}}, no effort is made to generate human-readable HTML.  Default is {{#t}}.
159
160
161=== Accents -> HTML entities translation
162
163==== ws:use-entities-translation
164
165    '''parameter:''' ws:use-entities-translation
166
167Translate special symbols into HTML entities (e.g., á becomes &aacute;). If no argument is provided, no translation is performed. Currently translation is only available for iso-8859-1 symbols (e.g., {{(ws:use-entities-translation 'iso-8859-1)}}).
168
169
170==== ws:iso-8859-1->html-entities
171
172    '''procedure:''' (ws:iso-8859-1->html-entities text)
173
174Converts iso-8859-1 text TEXT to HTML entities.
175
176
177=== GET and POST variables
178
179==== ws:with-get-vars
180
181    '''macro:''' (ws:with-get-vars VARLIST BODY)
182
183Binds all the HTTP GET method's variables listed in VARLIST to Scheme variables. If a listed variable is not available from the GET method, it's bound to {{#f}} in Scheme.
184
185Example:
186
187    (define (beavis&butthead)
188      (ws:with-get-vars (beavis butthead)
189        (ws:itemize
190         (list
191          (or beavis "no beavis")
192          (or butthead "no butthead")))))
193
194
195==== ws:post-vars
196
197    '''macro:''' (ws:with-post-vars VARLIST BODY)
198
199The same as {{ws:with-get-vars}}, but for HTTP POST method variables.
200
201
202==== ws:with-post/get-vars
203
204    '''macro:''' (ws:with-post/get-vars VARLIST BODY)
205
206The same as {{ws:with-get-vars}} and {{ws:with-get-vars}}, but first try to bind HTTP POST method variables, then GET.
207
208
209==== ws:http-vars
210
211    '''variable:''' ws:http-vars
212
213Variable which is bound to the list of the variables names (as strings) from the latest invocation of {{ws:with-post-vars}} or {{ws:with-get-vars}}. It's convenient to use with {{post-var}} and {{get-var}} from the [[spiffy-utils]] extension.
214
215Example:
216
217    (ws:with-post-vars (name address city)
218        (ws:make-table (map (lambda (var)
219                               (list var (post-var var)))
220                            ws:http-vars)))
221
222
223=== Debugging
224
225==== ws:debug-file
226
227    '''parameter:''' ws:debug-file
228
229A parameter which indicates the file where debugging messages are written. {{#f}} (default) means no debugging.
230
231
232==== ws:debug
233
234    '''procedure:''' (ws:debug . msgs)
235
236Write debugging information (MSGS) to the file configured by the {{ws:debug-file}} parameter.
237
238
239== Examples
240
241http://schemers.ucpel.tche.br/mario/examples
242
243== License
244
245This software is licensed under the BSD license.
246
247 Copyright (c) 2005, 2006, 2007 Mario Domenech Goulart.  All rights reserved.
248
249 Permission is hereby granted, free of charge, to any person obtaining a
250 copy of this software and associated documentation files (the Software),
251 to deal in the Software without restriction, including without limitation
252 the rights to use, copy, modify, merge, publish, distribute, sublicense,
253 and/or sell copies of the Software, and to permit persons to whom the
254 Software is furnished to do so, subject to the following conditions:
255 
256 The above copyright notice and this permission notice shall be included
257 in all copies or substantial portions of the Software.
258 
259 THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
260 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
261 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
262 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
263 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
264 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
265 OTHER DEALINGS IN THE SOFTWARE.
266
267== Version history
268
269; 0.84 : Fix for the {{embed}} tag, added {{noembed}} tag.
270
271; 0.83 : Support for tags: {{tbody}}, {{tfoot}} and {{embed}}
272
273; 0.82 : Explict use of srfi-69 (Thanks to Kon Lovett).
274
275; 0.81 : Fix for ws:-prefixed procedures.
276
277; 0.8 : {{ws:select}} instead of {{select}} to avoid name clash with chicken's {{select}} macro, wiki documentation, {{ws:debug}}, {{ws:debug-file}}, {{ws:human-readable-html}}
278
279; 0.7 : Added {{ws:table-colorizer}} and {{ws:iso-8859-1->html-entities}}, fix for the comment procedure.
280
281; 0.6 : {{css-file}} keyword argument for {{ws:page}} accepts a list of filenames, syntax for inlining CSS code in HTML pages ({{ws:page}}), {{body-attribs}} and {{charset}} keyword arguments ({{ws:page}}), fix for the {{meta}} tag, added {{ws:with-post/get-vars}} macro.
282
283; 0.5 : Nested scheme lists now produce nested HTML lists ({{ws:itemize}} and {{ws:enumerate}}), new tags and attributes, line-breaking fixing for some tags, added support for HTML attributes without value, better iso-8859-1 entities translation support, new procedures: {{ws:page}} and {{ws:load}}, several bugfixes.
284
285; 0.4.0 : Several changes (some backwards incompatible), code cleanup, better documentation, macros to bind GET and POST HTTP methods variables to Scheme variables, improved support for HTML tags
286
287; 0.3.5 : Support for link and a small addition to meta tags by Peter Busser
288
289; 0.3.4 : Added version and docs to setup script
290
291; 0.3.3 : Initial release as an egg
Note: See TracBrowser for help on using the repository browser.