Understanding #ajax_processed on Drupal 7 Form API

Working on a complex multi-steps AJAX form? Stuck trying to attach AJAX to a field? You may as well be informed on the usage of the internal property #ajax_processed, it could help you understand what's going on behind the scene.

First, this property of the Form API is used by ajax_pre_render_element() located in includes/ajax.inc. It's here that Drupal will decide whether to attach AJAX to your field or not.

I encourage you to open ajax_pre_render_element() sources on another tab. It may come in handy to better understand what I'm talking about.

What's going on?

Let's keep it simple. Here's what's gonna happen based on the current state of $element['#ajax_processed']:

#ajax_processed is set

If the #ajax_processed key already exists in the $element array, the function will stop and return the variable unchanged.
It means Drupal already has examined the element earlier and attached libraries and AJAX settings if #ajax was set and values were correct.

#ajax_processed is not set

If the #ajax_processed key does not already exist in the $element array, Drupal will determine its value.

When is #ajax_processed set to FALSE?

The #ajax_processe attribute is set to FALSE by default. Then, if the #ajax array doesn't contain valid settings, the function will end, returning $element with that only modification.

When is #ajax_processed set to TRUE?

For the attribute to switch from FALSE to TRUE, the #ajax array should have :

• A "callback" key storing the name of a callback function as a string.
• A "path" key storing the link to the ajax callback page (usually "system/ajax").
• A "type" key storing the field type.
• An "event" key (automatically defined earlier) storing the name of the DOM event to attach to the element from the browser.