source: project/release/2/ajax/doc.scm @ 8742

Last change on this file since 8742 was 8742, checked in by felix winkelmann, 12 years ago

moved eggs partially to rrb2

File size: 8.8 KB
Line 
1(use eggdoc)
2
3(define license
4"Copyright (c) 2005, Felix Winkelmann.  All rights reserved.
5
6Permission is hereby granted, free of charge, to any person obtaining a
7copy of this software and associated documentation files (the Software),
8to deal in the Software without restriction, including without limitation
9the rights to use, copy, modify, merge, publish, distribute, sublicense,
10and/or sell copies of the Software, and to permit persons to whom the
11Software is furnished to do so, subject to the following conditions:
12
13The above copyright notice and this permission notice shall be included
14in all copies or substantial portions of the Software.
15
16THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
20OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22OTHER DEALINGS IN THE SOFTWARE.")
23
24(define email "mailto:felix@call-with-current-continuation.org")
25
26(define doc
27  `((eggdoc:begin
28     (name "ajax")
29     (description (p "A basic interface to " (a (@ (href "http://en.wikipedia.org/wiki/Ajax_%28programming%29")) "AJAX")
30                     ", using the "
31                     (a (@ (href "http://prototype.conio.net/")) "Prototype")
32                     " javascript library (included)."))
33     
34     (author (url ,email "felix"))
35
36     (history
37      (version "1.8" "Fix for Ticket #315")
38      (version "1.7" "session support [Daishi Kato]")
39      (version "1.6" "Added key parameter to " (tt "ajax"))
40      (version "1.5" "Removed quoting from " (tt "remote-action") " argument parameter")
41      (version "1.4" "Updated prototype.js to version 1.4.0")
42      (version "1.3" "Fixed bug in handling of 'parameters' keyword arg")
43      (version "1.2" "Several enhancements by Daishi Kato")
44      (version "1.1" "Bugfix in " (tt "remote-button") " by Daishi Kato; " 
45               (tt "current-request") " and " (tt "current-urlencoded-arguments") 
46               " are now also available in callbacks")
47      (version "1.0" "Initial release"))
48
49     (requires 
50      (url "md5.html" "md5")
51      (url "spiffy.html" "spiffy")
52      (url "url.html" "url") )
53
54     (usage)
55     (download "ajax.egg")
56
57     (documentation
58      (p "This extension provides a set of procedures to use asynchronous callbacks from a browser to"
59         " a Chicken-powered web-server (for example " 
60         (a (@ (href "http://www.call-with-current-continuation.org/eggs/spiffy.html")) "Spiffy") ")."
61         " This is done using Prototype's wrappers around the " (tt "xmlHttpRequest") " API.") )
62
63     (group
64      (parameter "(ajax-output-format [SYMBOL])"
65                 (p "Specifies how HTML and script-fragments generated by the procedures of this"
66                    " package should be handled. " (tt "SYMBOL") " should be either " (tt "shtml") " or "
67                    (tt "html") ", where the former requests output as SXML expressions and the latter"
68                    " as text containing HTML. " (tt "html") " is the default.") ) 
69      (parameter "(ajax-callback-registration [PROCEDURE])"
70                 (p "Holds a procedure that will be called for every registered " (tt "xmlHttpRequest")
71                    " callback (see below).") ) )
72
73     (group
74      (procedure "(ajax [KEY [SCRIPTFILENAME]])"
75                 (p "Initializes callback handling for this page/response and returns a HTML or SHTML"
76                    " fragment containing a script element linking to the given source filename, which"
77                    " defaults to " (tt "prototype.js") ". The Prototype library is included in the"
78                    " distribution and will be installed in the extension repository.") 
79                 (p "The optional argument KEY is used to make the generated callback-URLs for this page more unique and may"
80                    " be an arbitrary string.")
81                 (p "This procedure resets the callback-handling for this response and must be called"
82                    " before using any of the " (tt "remote-...") " procedures described below.") )
83      (procedure "(remote-url THUNK [ARGUMENTS] [SESSIONID] [UNIQUEID] [LIFETIME])"
84                 (p "Registers a HTTP callback handler for a generated URL that invokes THUNK, a procedure with"
85                    " no arguments. If ARGUMENTS is given, then it should be a string or an association-list mapping"
86                    " URL-encoded argument-names to values. In both cases the arguments will be encoded in the url."
87                    " If SESSIONID and LIFETIME are given, this url will be expired when the LIFETIME in seconds is passed from the last access of urls with the SESSIONID. If UNIQUEID is given and not #f, it is used to remove the previous url with the same UNIQUEID.")
88                 (p "This procedure returns an URL as a string.") )
89      (procedure "(remote-action THUNK #!key arguments update insert-before insert-after insert-top insert-bottom method success failure name frequency eval-scripts sessionid uniqueid lifetime)"
90                 (p "Returns a string containing Javascript code to invoke the zero-argument procedure THUNK"
91                    " via an " (tt "xmlHttpRequest") " callback. Depending on the keyword arguments the result" 
92                    " returned from THUNK is treated as HTML or SHTML and describes a HTML fragment that should"
93                    " be used to modify the current document.")
94                 (p "The meaning of the various keyword arguments is as follows.")
95                 (table 
96                  (@ (border "0"))
97                  (tr (td (tt "arguments")) (td "A string or an association list of URL-encoded variable/value pairs ("
98                                                "see " (tt "remote-url") " for more information)"))
99                  (tr (td (tt "update")) (td "the id of a document node that should be replaced with the SXML of this reply"))
100                  (tr (td (tt "insert-before")) (td "Document-id of element before which the reply will be inserted"))
101                  (tr (td (tt "insert-after")) (td "Document-id of element after which the reply will be inserted"))
102                  (tr (td (tt "insert-top")) 
103                      (td "Document-id of element in which the reply will be inserted as the topmost sub-element"))
104                  (tr (td (tt "insert-bottom")) 
105                      (td "Document-id of element in which the reply will be inserted as the bottommost sub-element"))
106                  (tr (td (tt "method")) (td "HTTP request method used"))
107                  (tr (td (tt "success")) (td "Javascript code to be evaluated on successful reply"))
108                  (tr (td (tt "failure")) (td "Javascript code to be evaluated on non-succesful reply"))
109                  (tr (td (tt "name"))
110                      (td "The name of a Javascript variable which should be assigned to the created Prototype placeholder"
111                          " object"))
112                  (tr (td (tt "frequency")) (td "The interval in seconds after which the callback should be invoked")) 
113                  (tr (td (tt "eval-scripts")) (td "If true, evaluate JavaScript code received in the response"))
114                  (tr (td (tt "sessionid")) (td "Pass to remote-url"))
115                  (tr (td (tt "uniqueid")) (td "Pass to remote-url"))
116                  (tr (td (tt "lifetime")) (td "Pass to remote-url"))
117                  )
118                 (p "Note that the " (tt "update") ", " (tt "insert-...") ", " (tt "success") " and " (tt "failure") " arguments"
119                    " are mutually exclusive. If the " (tt "frequency") " argument is given, a periodical timer will be"
120                    " started (you can use the " (tt "name") " argument to obtain a reference to the timer and call the "
121                    (tt "start") " and " (tt "stop") " Javascript methods to control it).") )
122      (procedure "(remote-link TEXT THUNK KEYWORD-ARGUMENTS ...)"
123                 (p "Returns HTML or SHTML for a link (" (tt "<a>") ") that will invoke THUNK when clicked."
124                    " The KEYWORD-ARGUMENTS are the same as for " (tt "remote-action") "."))
125      (procedure "(remote-button TEXT THUNK KEYWORD-ARGUMENTS ...)"
126                 (p "Returns HTML or SHTML for a button (" (tt "<button>") ").") )
127      (procedure "(remote-timer FREQUENCY THUNK KEYWORD-ARGUMENTS ...)"
128                 (p "Returns HTML or SHTML for a Javascript element that starts a periodical timer triggered every"
129                    " FREQUENCY seconds.") ) )
130
131     (group
132      (procedure "(no-cache)"
133                 (p "Disables caching of the current page by setting various HTTP response headers. Handy for debugging.") ) )
134     
135     (examples
136      (p "Here we use the " (tt "ajax") " extension in an ssp page. To try it out you can invoke " (tt "csi") " like this (assuming "
137         (tt "prototype.js") " and " (tt "test.ssp") " are in the current directory):")
138      (pre #<<EOF
139$ csi -q
140#;1> (use spiffy)
141#;2> (start-server port: 8080 root: "." debug: #t)
142EOF
143)
144      (pre #<<EOF
145<!-- test.ssp -->
146<html>
147<head>
148<?scheme
149(use ajax)
150(no-cache)
151(display (ajax))
152(define words '(one two three))
153?>
154</head>
155<body>
156 The current time is: <span id="time"><b>...</b></span>
157 <p>
158 <ul id="list"></ul>
159 <p>
160 <?
161 (remote-timer 
162   2
163   (lambda () (printf "<b>~a</b>" (seconds->string (current-seconds))))
164   update: "time")
165 ?>
166 <p>
167 <?
168 (remote-button
169   "Click me" 
170   (lambda () (printf "<li>~a</li>" (list-ref words (random (length words)))))
171   insert-bottom: "list")
172 ?>
173</body>
174</html>
175EOF
176))
177     (section "License" (pre ,license)))))
178
179(eggdoc->html doc)
180
Note: See TracBrowser for help on using the repository browser.