Document AJAX no-js and use-ajax

subscribing

Excellent - I plan to do full Ajax docs for the new system and will try to cover this. As of now, I haven't explored it.

I'm not to no-js yet, but

1. Updated the 6-to-7 documentation at http://drupal.org/update/modules/6/7#ahah-now-ajax
2. Committed the D7 version of the Ajax Example to the Examples Module

I would appreciate review of those two, plus contributions of more sophisticated AJAX examples. There's a lot more stuff in here!

The coolest thing in the world is how simple the callbacks have become. One line for each of my examples. I guess we could have figured out how to do away with the callback entirely if you wanted to replace the entire form.

May I hijack this issue for a general To-Do list for Ajax Documentation? There are several different issues that need to be addressed. I will maintain this comment as time goes on.

• D6 to D7 upgrade information (Currently covers what you need to know for existing code, but doesn't cover any AJAX new features.) I'm going to call this one good.
• General change to 'callback' from 'path' in forms.
• Change to replacing the entire div instead of just the contents.
• How to use 'path' if you had to (build on ajax_form_callback() ) (Perhaps not necessary)
• #599804: Unify page, AJAX 'path', and AJAX 'callback' callbacks made the Ajax callback behave like a page callback.
• #367567: Use AJAX framework for "Add more" / load include file containing form / introduce $form_state['build_info'] - not sure what changes this introduced.
• #544418: Integrate CTools AJAX framework with Drupal to extend (and replace) existing ahah framework - Introduced the entire commands framework. There is phpdoc documentation on this but it probably needs more perspective, and IMO should move out of phpDoc and into the handbook.
• Topics in commands: no_js, use-ajax
• #551694: Standardize the return of status messages in AJAX callbacks - Changed how status messages are handled. Status message handling should be discussed.
• Good examples. The Examples module now has an Ajax Example module, which shows basic forms use of AJAX. We need to introduce some of the more sophisticated things that are available.
• the callback from drupal_get_form() changed signature and now takes $form and $form_state as arguments. Mention this, as it's a stumbling block. (Already updated on module upgrade page.
• 2009-11-25: Updated the Forms API reference to show current usage
• How to handle system messages resulting from AJAX actions. Automatic and manual handling. #551694: Standardize the return of status messages in AJAX callbacks

Other items that should be covered? Chime in!

For now, subscribing. When I'm able to, I'd also like to help.

I confirm that this approach works. Thanks so much for the detective work!

Thanks for mentioning this issue in IRC (was afk therefore I couldn't reply there). The examples (also the ones in examples module) are helpful when working with ctools wizard ajax render callback (D6), too. There in the ajax-responder.js the click event is attached to links.

I was playing around with the AJAX framework this morning, and came across a relatively new use case: adding new custom commands.

I wanted to add some commands for working with a jQuery UI Dialog. An example of my approach, which is working but not fully tested, follows:

mymodule.module

/**
 * Return an ajax command array to set the dialog options.
 *
 * @param $options
 * An array of jQuery UI dialog options, keyed by option name.
 */
function mymodule_ajax_command_dialog_options($selector, $options, $settings = NULL) {
  return array(
    'command' => 'mymodule_dialog_options',
    'options' => $options,
    'settings' => $settings,
  );
}

mymodule.js

Drupal.behaviors.mymodule = {
  attach: function(context, settings) {    
    // Add custom commands to Drupal.ajax objects.
    for (var i in Drupal.ajax) {
      Drupal.mymodule.addCommands(Drupal.ajax[i]);
    }
  }
};

// Add custom commands to a Drupal.ajax object.
Drupal.mymodule.addCommands = function (ajax) {
  //Add options dialog command to ajax object.
  ajax.commands.mymodule_dialog_options = function (ajax, response, status) {
    options = response.options;
    if (options) {
      for (var option in options) {
        $(response.selector).dialog('option', option, options[option]);
      }
    }
  }
}

The result is that I can add the 'mymodule_dialog_options' command in my ajax callbacks and my custom command function runs on the client side.

So here is an actual question :)

Is there a better way to add these commands to the Drupal.ajax object(s)? The way I got it working, is adding the command to each Drupal.ajax object that exists one-by-one. The better approach, which I could not get working, would be to add it to all Drupal.ajax objects in one swoop. This is where my javascript mastery falls a bit short. I initialy tried to do this:

Drupal.ajax.commands.prototype.mymodule_dialog_options = function() { ...

But I guess the Drupal.ajax object is not extendable in this way?

Committed update to forms_api_reference.html updating to current AJAX situation.

http://drupal.org/cvs?commit=294182

This documentation-only patch adds significant information to the AJAX overview in ajax.inc.

New topics covered or with improved coverage include:

• A simple example
• How status messages are handled.

Plus lots of little cleanup.

It's nearly impossible to review a doc change as a patch, so attached is the HTML rendered by the API module. It doesn't show what's changed, but really, everything is open for improvement.

#13: drupal.ajax_documentation_610068_13.patch queued for re-testing.

Good by me. Marking RTBC - thanks for the review and improvement.

The bot approved #17 despite the lack of marking on it: See http://qa.drupal.org/pifr/test/26734

For other reviewers, #17 is still exactly the same as #13 (which you can read as HTML in the attachment to #14) - except for the following change.

--- includes/ajax.inc
+++ includes/ajax.inc
@@ -152,10 +152,11 @@
  * be converted to a JSON object and returned to the client, which will then
  * iterate over the array and process it like a macro language.
  *
- * Each command is an object. $object->command is the type of command and will
- * be used to find the method (it will correlate directly to a method in
- * the Drupal.ajax[command] space). The object may contain any other data that
- * the command needs to process.
+ * Each command item is an associative array which will be converted to a command
+ * object on the JavaScript side. $command_item['command'] is the type of
+ * command, e.g. 'alert' or 'replace', and will correspond to a method in the
+ * Drupal.ajax[command] space. The command array may contain any other data
+ * that the command needs to process, e.g. 'method', 'selector', 'settings', etc.
  *
  * Commands are usually created with a couple of helper functions, so they
  * look like this:

Committed to CVS HEAD. Thanks.

Remaining items to do in #4

I think that no-js and use-ajax are the last remaining items to be documented in this issue

I'll put this on my list for docs day.

@katbailey, could you write a quick description here of what you think should be said? 'twould be much appreciated.

I'm going to say that http://api.drupal.org/api/group/ajax/7 + the AJAX link example are good enough.

Hmm... I don't find anything about class="no-js" *anywhere* in D7 code or documentation. Did I miss something?

// menu callback for the 'ajaxy' path
function ajaxy_ajax_response($type = 'ajax') {
  $output=strftime('%c');
  if ($type == 'ajax') {
    $commands = array();
    $commands[] = ajax_command_append('#myDiv', $output);
    $page = array('#type' => 'ajax_commands', '#ajax_commands' => $commands);
    ajax_deliver($page);
  }
  else {
    return $output;
  }

This code as proposed by katbaily is unsuitable for dynamic content. I always get the same date/time here (see changed ajax response code above). No effect when I clear the browser cache in between. Only reloading the page where this link is helps. How do I "uncache" it? Would be good to include that too in the examples and documentation.

Forget my post. For some obscure reason now it works.

New data attributes are being added to links with the use-ajax class in #3026636: Allow AJAX links to replace a specific selector (CR: https://www.drupal.org/node/3031444).
This probably needs to be taken into account when writing the documentation for the AJAX links.

As far as I can tell, the ajax link support the following data attributes:

• data-dialog-type: This is either 'modal' or 'dialog'
• data-dialog-options: Should be a JSON encoded string of options for Drupal.dialog. Basically all options supported by http://api.jqueryui.com/dialog/ can be used and are just passed along to the jQuery UI dialog.
• data-dialog-renderer: Has been added in #2844261: Allow dialog links to specify a renderer in addition to a dialog type. It appears to be used to specify how a dialog should be rendered. offcanvas is an example, but not sure which other values are supported and how that works in detail.

The content is always being fetched from the href attribute of the link.

#3026636: Allow AJAX links to replace a specific selector adds the following attributes:

• data-ajax-wrapper: This accepts the ID of the HTML element (without the #) that should be replaced by the content fetched via AJAX. The AJAX system already supported setting the wrapper for Drupal.Ajax, this behavior has not been changed. Now AJAX links can also use this.
• data-ajax-progress: By default the AJAX links used the throbber progress indicator. AJAX links can now override the default with this data attribute (by setting this to 'fullscreen' for example).
• data-ajax-focus: This accepts a jQuery selector targeting the element that should receive focus. By default the the focus is returned to the AJAX link after the AJAX request is handled. AJAX links can now override this default with this data attribute. This was added to improve accessibility.

I ran into this old issue but couldn't find any documentation page for use-ajax for Drupal 8. Does this docs page already exist somewhere?

I added a documentation for Ajax Dialogs to the AJAX API Guide that explains how to use the use-ajax class to display Dialogs. If there's no other docs page for use-ajax yet, I'd add a documentation page to the AJAX API Guide that focuses on use-ajax and use-ajax-submit.