Outdated egg!

This is an egg for CHICKEN 3, the unsupported old release. You're almost certainly looking for the CHICKEN 4 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

ajax
  1. Outdated egg!
  2. ajax
    1. Description
    2. Author
    3. Requires
  3. Usage
  4. Download
    1. Documentation
    2. Example
    3. Version history
    4. License

Description

A basic interface to AJAX, using the Prototype javascript library (included).

Author

Felix Winkelmann. Currently maintained by Mario Domenech Goulart.

Requires

Usage

(require-extension ajax)

Download

ajax.egg

Documentation

This extension provides a set of procedures to use asynchronous callbacks from a browser to a Chicken-powered web-server (for example Spiffy). This is done using Prototype's wrappers around the xmlHttpRequest API.

[parameter] (ajax-output-format [SYMBOL])

Specifies how HTML and script-fragments generated by the procedures of this package should be handled. SYMBOL should be either shtml or html, where the former requests output as SXML expressions and the latter as text containing HTML. html is the default.

[parameter] (ajax-callback-registration [PROCEDURE])

Holds a procedure that will be called for every registered xmlHttpRequest callback (see below).

[procedure] (ajax [KEY [SCRIPTFILENAME]])

Initializes callback handling for this page/response and returns a HTML or SHTML fragment containing a script element linking to the given source filename, which defaults to prototype.js. The Prototype library is included in the distribution and will be installed in the extension repository.

The optional argument KEY is used to make the generated callback-URLs for this page more unique and may be an arbitrary string.

This procedure resets the callback-handling for this response and must be called before using any of the remote-... procedures described below.

[procedure] (remote-url THUNK [ARGUMENTS] [SESSIONID] [UNIQUEID] [LIFETIME])

Registers a HTTP callback handler for a generated URL that invokes THUNK, a procedure with no arguments. If ARGUMENTS is given, then it should be a string or an association-list mapping URL-encoded argument-names to values. In both cases the arguments will be encoded in the url. 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.

This procedure returns an URL as a string.

[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)

Returns a string containing Javascript code to invoke the zero-argument procedure THUNK via an xmlHttpRequest callback. Depending on the keyword arguments the result returned from THUNK is treated as HTML or SHTML and describes a HTML fragment that should be used to modify the current document.

The meaning of the various keyword arguments is as follows.

arguments
A string or an association list of URL-encoded variable/value pairs (see remote-url for more information)
update
the id of a document node that should be replaced with the SXML of this reply
insert-before
Document-id of element before which the reply will be inserted
insert-after
Document-id of element after which the reply will be inserted
insert-top
Document-id of element in which the reply will be inserted as the topmost sub-element
insert-bottom
Document-id of element in which the reply will be inserted as the bottommost sub-element
method
HTTP request method used
success
Javascript code to be evaluated on successful reply
failure
Javascript code to be evaluated on non-succesful reply
name
The name of a Javascript variable which should be assigned to the created Prototype placeholder object
frequency
The interval in seconds after which the callback should be invoked
eval-scripts
If true, evaluate JavaScript code received in the response
sessionid
Pass to remote-url
uniqueid
Pass to remote-url
lifetime
Pass to remote-url

Note that the update, insert-..., success and failure arguments are mutually exclusive. If the frequency argument is given, a periodical timer will be started (you can use the name argument to obtain a reference to the timer and call the start and stop Javascript methods to control it).

[procedure] (remote-link TEXT THUNK KEYWORD-ARGUMENTS ...)

Returns HTML or SHTML for a link (<a>) that will invoke THUNK when clicked. The KEYWORD-ARGUMENTS are the same as for remote-action.

[procedure] (remote-button TEXT THUNK KEYWORD-ARGUMENTS ...)

Returns HTML or SHTML for a button (<button>).

[procedure] (remote-timer FREQUENCY THUNK KEYWORD-ARGUMENTS ...)

Returns HTML or SHTML for a Javascript element that starts a periodical timer triggered every FREQUENCY seconds.

[procedure] (no-cache)

Disables caching of the current page by setting various HTTP response headers. Handy for debugging.

Example

Here we use the ajax extension in an ssp page:

<!-- test.ssp -->
<html>
 <head>
  <?scheme
  (use ajax)
  (no-cache)
  (display (ajax))
  (define words '(one two three))
  ?>
 </head>
 <body>
  The current time is: <span id="time"><b>...</b></span>
  <p>
  <ul id="list"></ul>
  <p>
  <?
  (remote-timer 
    2
    (lambda () (printf "<b>~a</b>" (seconds->string (current-seconds))))
    update: "time")
  ?>
  <p>
  <?
  (remote-button
    "Click me" 
    (lambda () (printf "<li>~a</li>" (list-ref words (random (length words)))))
    insert-bottom: "list")
  ?>
 </body>
</html>

To try it out you can invoke csi like this (assuming prototype.js and test.ssp are in the current directory):

$ csi -q
#;1> (use spiffy ssp-handler)
#;2> (spiffy-file-ext-handlers `(("ssp" . ,ssp-handler)))
#;3> (start-server port: 8080 root: "." debug: #t)

Version history

License

 
 Copyright (c) 2005-2008, Felix Winkelmann and Mario Domenech Goulart.
 All rights reserved.
 
 Permission is hereby granted, free of charge, to any person obtaining a
 copy of this software and associated documentation files (the Software),
 to deal in the Software without restriction, including without limitation
 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 and/or sell copies of the Software, and to permit persons to whom the
 Software is furnished to do so, subject to the following conditions:
 
 The above copyright notice and this permission notice shall be included
 in all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.