chickadee » awful » ajax

Generate javascript code to be added to the page defined by define-page. Return the generated javascript code (which usually is not useful, so should be discarded).

path is the URL path (a string) of the server side handler. This path is placed under the (app-root-path)/(ajax-namespace) path. So, if your app-root-path is "my-app", your ajax-namespace is "ajax" and you use "do-something" as the first argument to ajax, the URL for the server side handler would be "/my-app/ajax/do-something".

selector is the selector for the DOM element to be observed. If it is a quoted symbol, awful generates a JQuery selector by DOM id (e.g., 'my-selector generates "#my-selector"). If it is a string, awful uses it as-is to generate the JQuery selector (e.g., "input[name^=omg]" generates "input[name^=omg]").

event (a quoted symbol or a list) is the event(s) to be observed. If it is a quoted symbol (e.g., 'click), only this event will be bound. If event is a list of events, all the events from the list will be bound.

proc is a no-argument procedure to be executed on the server side.

The target keyword parameter is the id of the DOM element to be affected by the result of proc.

The method (a quoted symbol, usually 'GET or 'POST) keyword parameter is the HTTP method to be used by the ajax request.

The arguments keyword parameter is an alist mapping request variables (symbols) to their values (strings). ajax uses these arguments to assembly the query string or the request body to send to the server when performing the ajax request.

Example:

arguments: '((var1 . "$('#var1').val()")
             (var2 . "$('#var2').val()"))

If the no-session keyword parameter is #t, it means that no session should be considered (ajax implicit sends the session identifier when no-session is #f).

If the no-db keyword parameter is #t, it means that the should be no attempt to connect the database, even when database usage is activated by enable-db and db-credentials is not #f.

The vhost-root-path keyword parameter (a string) is the vhost root path. It is useful for explicitly separate pages defined using the same path (see define-page) but for different vhosts.

The live keyword parameter (boolean) indicates wheter ajax should use JQuery's live method (see http://api.jquery.com/live/).

The prelude keyword parameter (string) is an arbitrary piece of javascript code to be placed right before the ajax request.

The update-targets keyword parameter a boolean indicating whether multiple targets should be updated upon ajax response. When update-targets is used, the procedure proc used as argument to ajax should yield an alist as result. The alist maps DOM elements identifiers to their corresponding values.

Here's an example:

(use awful html-tags)

(enable-ajax #t)

(define-page (main-page-path)
  (lambda ()

    (ajax "foo" 'foo 'click
          (lambda ()
            '((a . 1) (b . 2) (c . 3)))
          update-targets: #t)

    (<div>
     (link "#" "foo" id: "foo")
     (<div> id: "a")
     (<div> id: "b")
     (<div> id: "c"))))

The success keyword parameter (string) can be any arbitrary javascript code to be executed on the successful ajax request. The javascript code can assume that a variable response is bound and contains the request resulting data. Here's an example:

(use awful html-tags)

(enable-ajax #t)

(define-page (main-page-path)
  (lambda ()

    (ajax "foo" 'foo "click"
          (lambda ()
            "hey")
          success: "$('#bar').html(response + ' you!')")

    (++ (link "#" "foo" id: "foo")
        (<div> id: "bar"))))

The cache keyword parameter (boolean), if set to #f, it will force requested pages not to be cached by the browser. The default value is not set, leaving it to be set by JQuery. See JQuery's documentation for further details.

The error-handler keyword parameter expects a JavaScript callback to be used as the error handler for the Ajax request. See the error attribute for the settings object given as argument to jQuery.ajax (http://api.jquery.com/jQuery.ajax/).

The ajax procedure is session, HTTP request and database -aware.