chickadee » awful » ajax

Generate JavaScript code to be added to the page defined by define-page. Return the generated JavaScript code. Unless no-page-javascript is a truthy value, the JavaScript code will be added to the page in which case the returned JavaScript code is usually not useful and can 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.

If use-sxml is #t, it specifies that the ajax handler produces SXML code instead of strings.

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 on keyword parameter (boolean) indicates whether ajax should use jQuery's on method (see http://api.jquery.com/on/). If on gets bound to #t, awful will generate code to start delegating events from the document DOM element. If on gets bound to a symbol, awful will generate code to start delegating events from DOM element whose id is the given symbol. If on gets bound to a string, awful will generate code to start delegating events from DOM element which matches the given string representing a selector. The on keyword parameter was introduced in awful 0.39.2.

The live keyword parameter (boolean) indicates whether ajax should use jQuery's live method (see http://api.jquery.com/live/). Note that the live method was deprecated in jQuery 1.7 and removed in version 1.9. If you are using a more recent version of jQuery, see the on keyword parameter for ajax (introduced in awful 0.39.2).

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:

(cond-expand
  (chicken-4
    (use awful))
  (chicken-5
    (import awful)))

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

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

    `(,(link "#" "Click me" id: "foo")
      (div (@ (id "a")))
      (div (@ (id "b")))
      (div (@ (id "c")))))
  use-ajax: #t)

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:

(cond-expand
  (chicken-4
    (use awful))
  (chicken-5
    (import awful)))

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

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

    `(,(link "#" "Click me" id: "foo")
      (div (@ (id "bar")))))
  use-ajax: #t)

When success is used together with target or update-targets, the success code runs before the update code. This allows to update parts of the dom that cannot be identified by id (e.g., attributes), post-process the response before targets are updated, or skip the update altogether by performing a return from the callback function. Here's an example:

(cond-expand
  (chicken-4
    (use awful))
  (chicken-5
    (import awful)))

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

    (ajax "foo" 'foo 'click
          (lambda ()
            '((lang . "en") (a . 1) (b . 2) (c . 3)))
          update-targets: #t
          success: "document.documentElement.lang = response['lang'];")

    `(,(link "#" "Click me" id: "foo")
      (span (@ (id "lang") (display "none")))
      (div (@ (id "a")))
      (div (@ (id "b")))
      (div (@ (id "c")))))
  use-ajax: #t)

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 no-page-javascript keyword parameter is a boolean that determines whether the generated JavaScript code is automatically added to the page or not. Defaults to #f. This parameter may be useful if you want more control of where or when the generated JavaScript code gets added to the page or even if it gets added at all.

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