The Cake Ajax helper utilizes the ever-popular Prototype and script.aculo.us libraries for Ajax operations and client side effects. In order to use this helper, you must have a current version of the JavaScript libraries from http://script.aculo.us placed in /app/webroot/js/. In addition, any views that plan to use the Ajax Helper will need to include those libraries.

Most of the functions in this helper expect a special $options array as a parameter. This array is used to specify different things about your Ajax operation. Here are the different values you can specify:

/* General Options */

$options['url']         // The URL for the action you want to be called.

$options['frequency']   // The number of seconds between remoteTimer() or
                        // observeField() checks are made.

$options['update']      // The DOM ID of the element you wish to update with
                        // the results of an Ajax operation.

$options['with']        // The DOM ID of the form element you wish to serialize
                        // and send with an Ajax form submission.

$options['type']        // Either 'asynchronous' (default), or 'synchronous'.
                        // Allows you to pick between operation types.

/* Callbacks : JS code to be executed at certain
   times during the XMLHttpRequest process */

$options['loading']     // JS code to be executed when the remote document
                        // is being loaded with data by the browser.

$options['loaded']      // JS code to be executed when the browser has finished
                        // loading the remote document.

$options['interactive'] // JS code to be executed when the user can interact
                        // with the remote document, even though it has not
                        // finished loading.

$options['complete']    // JS code to be called when the XMLHttpRequest is
                        // complete.

$options['confirm']     // Text to be displayed in a confirmation dialog before
                        // a XMLHttpRequest action begins.

$options['condition']   // JS condition to be met before the XMLHttpRequest
                        // is initiated.

$options['before']      // JS code to be called before request is initiated.

$options['after']       // JS code to be called immediately after request was
                        // initiated and before 'loading'.

Here are the helper's functions for making Ajax in Cake quick and easy:

Displays linked text $title, which retrieves the remote document at $options['url'] and updates the DOM element $options['update']. Callbacks can be used with this function.

This function creates the JavaScript needed to make a remote call. It is primarily used as a helper for linkToRemote. This isn't often used unless you need to generate some custom scripting.

Periodically calls the specified action at $options['url'], every $options['frequency'] seconds (default is 10). Usually used to update a specified div (specified by $options['update']) with the results of the remote call. Callbacks can be used with this function.

Returns a form tag that will submit to the action at $action using XMLHttpRequest in the background instead of the regular reload-required POST submission. The form data from this form will act just as a normal form data would (i.e. it will be available in $this->params['form']). The DOM element specified by $options['update'] will be updated with the resulting remote document. Callbacks can be used with this function.

Observes the field with the DOM ID specified by $field_id (every $options['frequency'] seconds) and calls the action at $options['url'] when its contents have changed. You can update a DOM element with ID $options['update'] or specify a form element using $options['with'] as well. Callbacks can be used with this function.

Works the same as observeField(), only this observes all the elements in a given form.

Renders a text field with ID $field with autocomplete. The action at $url should be able to return the autocomplete terms: basically, your action needs to spit out an unordered list (<ul></ul>) with list items that are the auto complete terms. If you wanted an autocomplete field that retrieved the subjects of your blog posts, your controller action might look something like:

function autocomplete () 
{
    $this->set('posts',
        $this->Post->findAll(
            "subject LIKE '{$this->data['Post']['subject']}'")
        );
    $this->layout = "ajax";
}

And your view for the autocomplete() action above would look something like:

<ul>
<?php foreach($posts as $post): ?>
<li><?php echo $post['Post']['subject']; ?></li>
<?php endforeach; ?>
</ul>

The actual auto-complete field as it would look in a view would look like this:

<form action="/users/index" method="POST">
    <?php echo $ajax->autoComplete('Post/subject', '/posts/autoComplete')?>
    <?php echo $html->submit('View Post')?>
</form>

The autoComplete() function will use this information to render a text field, and some divs that will be used to show the autocomplete terms supplied by your action. You might also want to style the view with something like the following:

<style type="text/css">

div.auto_complete {
    position         :absolute;
    width            :250px;
    background-color :white;
    border           :1px solid #888;
    margin           :0px;
    padding          :0px;
}

li.selected { background-color: #ffb; }

</style>

Makes the DOM element with ID $id draggable. There are some additional things you can specify using $options:

// (The version numbers refer to script.aculo.us versions)

$options['handle']     // (v1.0) Sets whether the element should only be
                       // draggable by an embedded handle. The value must be
                       // an element reference or element id.

$options['handle']     // (V1.5) As above, except now the value may be a
                       // string referencing a CSS class value. The first
                       // child/grandchild/etc. element found within the
                       // element that has this CSS class value will be used
                       // as the handle.

$options['revert']     // (V1.0) If set to true, the element returns to its
                       // original position when the drags ends.

$options['revert']     // (V1.5) Revert can also be an arbitrary function
                       // reference, called when the drag ends.

$options['constraint'] // If set to horizontal or vertical, the drag will
                       // be constrained to take place only horizontally or
                       // vertically.

Makes the DOM element with ID $id drop-able. There are some additional things you can specify using $options:

$options['accept']      // Set accept to a string or a JavaScript array of
                        // strings describing CSS classes. The Droppable will
                        // only accept Draggables that have one or more of
                        // these CSS classes.

$options['containment'] // The droppable element will only accept the
                        // draggable element if it is contained in the given
                        // elements (or element ids). Can be a single element
                        // or a JS array of elements.

$options['overlap']     //If set to horizontal or vertical, the droppable
                        // will only react to a draggable element if its
                        //overlapping by more than 50% in the given direction.

Used to create a drop target that initiates a XMLHttpRequest when a draggable element is dropped on it. The $options are the same as in drop(), and the $ajaxOptions are the same as in link().

Makes a list or group of floated objects (specified by DOM element ID $id) sortable. The $options array can configure your sorting as follows:

$options['tag']         // Sets the kind of tag (of the child elements of the
                        // container) that will be made sortable. For UL and
                        // OL containers, this is LI, you have to provide
                        // the tag kind for other sorts of child tags.
                        // Defaults to 'li'.

$options['only']        // Further restricts the selection of child elements
                        // to only encompass elements with the given CSS class
                        // (or, if you provide an array of strings, on any of
                        // the classes).

$options['overlap']     // Either vertical(default) or horizontal. For
                        // floating sortables or horizontal lists, choose
                        // horizontal. Vertical lists should use vertical.

$options['constraint']  // Restricts the movement of draggable elements,
                        // 'vertical' or 'horizontal'.

$options['containment'] // Enables dragging and dropping between Sortables.
                        // Takes an array of elements or element-ids (of the
                        // containers).

$options['handle']      // Makes the created draggable elemetns use handles,
                        // see the handle option on drag().

Creates an in-place ajax editor using the element with the DOM id supplied as the first parameter. When implemented, the element will highlight on mouseOver, and will turn into a single text input field when clicked. The second parameter is the URL that the edited data should be sent to. The action should also return the updated contents of the element. Additional options for the in-place editor can be found on the Script.aculo.us wiki.

The JavaScript helper is used to aid the developer in outputting well-formatted Javascript-related tags and data.

Used to return $script placed within JavaScript &lt;script&gt; tags.

Returns a JavaScript include tag pointing to the script referenced by $url.

Same as link(), only the include tag assumes that the script referenced by $url is not hosted on the same domain.

Escapes carriage returns and single and double quotes for JavaScript code segments.

Attaches an event to an element. Used with the Prototype library.

Caches JavaScript events created with event().

Writes cached events cached with cacheEvents().

The Number helper includes a few nice functions for formatting numerical data in your views.

Returns $number formatted to the level of precision specified by $precision.

Returns a human readable size, given the $size supplied in bytes. Basically, you pass a number of bytes in, and this function returns the appropriate human-readable value in KB, MB, GB, or TB.

Returns the given number formatted as a percentage, limited to the precision specified in $precision.

The Text Helper provides methods that a developer may need for outputting well formatted text to the browser.

Returns $text, with every occurance or $phrase wrapped with the tags specified in $highlighter.

Returns $text, with all HTML links (&lt;a href= ...) removed.

Returns $text with URLs wrapped in corresponding &lt;a&gt; tags.

Returns $text with email addresses wrapped in corresponding &lt;a&gt; tags.

Returns $text with URLs and emails wrapped in corresponding &lt;a&gt; tags.

Returns the first $length number of characters of $text followed by $ending ('...' by default).

Extracts an excerpt from the $text, grabbing the $phrase with a number of characters on each side determined by $radius.

Text-to-html parser, similar to Textile or RedCloth, only with a little different syntax.

The Time Helper provides methods that a developer may need for outputting Unix timestamps and/or datetime strings into more understandable phrases to the browser.

Dates can be provided to all functions as either valid PHP datetime strings or Unix timestamps.

Returns a UNIX timestamp, given either a UNIX timestamp or a valid strtotime() date string.

Returns a nicely formatted date string. Dates are formatted as "D, M jS Y, H:i", or 'Mon, Jan 1st 2005, 12:00'.

Formats date strings as specified in nice(), but ouputs "Today, 12:00" if the date string is today, or "Yesterday, 12:00" if the date string was yesterday.

Returns true if given datetime string is today.

Returns a partial SQL string to search for all records between two dates.

Returns a partial SQL string to search for all records between two times occurring on the same day.

Returns true if given datetime string is within current year.

Returns true if given datetime string was yesterday.

Returns true if given datetime string is tomorrow.

Returns a UNIX timestamp from a textual datetime description. Wrapper for PHP function strtotime().

Returns a date formatted for Atom RSS feeds.

Formats date for RSS feeds

Returns either a relative date or a formatted date depending on the difference between the current time and given datetime. $datetime should be in a strtotime-parsable format like MySQL datetime.

Works much like timeAgoInWords(), but includes the ability to create output for timestamps in the future as well (i.e. "Yesterday, 10:33", "Today, 9:42", and also "Tomorrow, 4:34").

Returns true if specified datetime was within the interval specified, else false. The time interval should be specifed with the number as well as the units: '6 hours', '2 days', etc.