According to webchick's first paragraph in
#633156-18: Need tests for AJAX Commands →
, most PHP developers don't understand Drupal's AJAX framework, and while that comment may have refered to the framework itself rather than how to use it, I think it's also true that even using it is complex. Fortunately, rfay has done some great work with respect to documentation and examples:
📌
Document AJAX no-js and use-ajax
Fixed
. Also, fortunately, the D7 AJAX framework has made some massive improvements over the D6 AHAH framework, both in terms of power and ease of use.
But I'm concerned that it's still not obvious enough how one is supposed to add AJAX functionality to a form, and how to do it in an accessible way (i.e., how to make sure the form also works when javascript is disabled). The problem is #ajax['callback']. Is it sufficently clear that this callback should only return content, and should not contain any form processing logic? If I weren't familiar with the FAPI and AJAX frameworks, I would not know this. I would think, ok here's a button, here's its #ajax['callback'] function, this is where I should do stuff in response to that button being clicked. I might not consider what should happen if javascript is disabled, and if I did, I would probably have nasty code duplication in my module.
If it weren't this late in the release cycle, I would propose renaming #ajax['callback'] to #ajax['return_callback'] to help point attention that this callback should be fairly limited in what it does. But given where we are in the release cycle, I don't think that's a good idea.
Instead, I propose adding some comments within the code, but also adding a #ajax['return_element'] property that can be used instead of a callback. I suspect that a majority of contrib module use-cases for AJAX won't need to do anything in the callback function other than retrieve the element that got updated. Let's make using AJAX even easier for these use-cases, by enabling them to be implemented with no callback function to worry about. This makes the framework easier to get started with, and comes with built-in accessibility compliance.
See patch for details, which also includes the poll module switching to this approach.