Adds Ajax information about an element to communicate with JavaScript.

If #ajax is set on an element, this additional JavaScript is added to the page header to attach the Ajax behaviors. See ajax.js for more information.

Parameters

array $element: An associative array containing the properties of the element. Properties used:

• #ajax['event']
• #ajax['prevent']
• #ajax['url']
• #ajax['httpMethod']
• #ajax['callback']
• #ajax['options']
• #ajax['wrapper']
• #ajax['parameters']
• #ajax['effect']
• #ajax['accepts']

Return value

array The processed element with the necessary JavaScript attached to it.

6 calls to RenderElementBase::preRenderAjaxForm()

FormElement::preRenderAjaxForm in core/lib/Drupal/Core/Render/Element/FormElement.php

Adds Ajax information about an element to communicate with JavaScript.

Link::preRenderLink in core/lib/Drupal/Core/Render/Element/Link.php

Pre-render callback: Renders a link into #markup.

RenderElement::preRenderAjaxForm in core/lib/Drupal/Core/Render/Element/RenderElement.php

Adds Ajax information about an element to communicate with JavaScript.

RenderElementBase::processAjaxForm in core/lib/Drupal/Core/Render/Element/RenderElementBase.php

Form element processing handler for the #ajax form property.

RenderElementTest::testPreRenderAjaxForm in core/tests/Drupal/Tests/Core/Render/Element/RenderElementTest.php

@covers ::preRenderAjaxForm

... See full list

2 methods override RenderElementBase::preRenderAjaxForm()

FormElement::preRenderAjaxForm in core/lib/Drupal/Core/Render/Element/FormElement.php

Adds Ajax information about an element to communicate with JavaScript.

RenderElement::preRenderAjaxForm in core/lib/Drupal/Core/Render/Element/RenderElement.php

Adds Ajax information about an element to communicate with JavaScript.

File

core/lib/Drupal/Core/Render/Element/RenderElementBase.php, line 258

Class

RenderElementBase

Provides a base class for render element plugins.

Namespace

Drupal\Core\Render\Element

Code

public static function preRenderAjaxForm($element) {
    // Skip already processed elements.
    if (isset($element['#ajax_processed'])) {
        return $element;
    }
    // Initialize #ajax_processed, so we do not process this element again.
    $element['#ajax_processed'] = FALSE;
    // Nothing to do if there are no Ajax settings.
    if (empty($element['#ajax'])) {
        return $element;
    }
    // Add a data attribute to disable automatic refocus after ajax call.
    if (!empty($element['#ajax']['disable-refocus'])) {
        $element['#attributes']['data-disable-refocus'] = "true";
    }
    // Add a data attribute to attempt to focus element that was focused before
    // executing ajax commands.
    if ($element['#ajax']['refocus-blur'] ?? FALSE) {
        $element['#attributes']['data-refocus-blur'] = "true";
    }
    // Add a reasonable default event handler if none was specified.
    if (isset($element['#ajax']) && !isset($element['#ajax']['event'])) {
        switch ($element['#type']) {
            case 'submit':
            case 'button':
            case 'image_button':
                // Pressing the ENTER key within a textfield triggers the click event of
                // the form's first submit button. Triggering Ajax in this situation
                // leads to problems, like breaking autocomplete textfields, so we bind
                // to mousedown instead of click.
                // @see https://www.drupal.org/node/216059
                $element['#ajax']['event'] = 'mousedown';
                // Retain keyboard accessibility by setting 'keypress'. This causes
                // ajax.js to trigger 'event' when SPACE or ENTER are pressed while the
                // button has focus.
                $element['#ajax']['keypress'] = TRUE;
                // Binding to mousedown rather than click means that it is possible to
                // trigger a click by pressing the mouse, holding the mouse button down
                // until the Ajax request is complete and the button is re-enabled, and
                // then releasing the mouse button. Set 'prevent' so that ajax.js binds
                // an additional handler to prevent such a click from triggering a
                // non-Ajax form submission. This also prevents a textfield's ENTER
                // press triggering this button's non-Ajax form submission behavior.
                if (!isset($element['#ajax']['prevent'])) {
                    $element['#ajax']['prevent'] = 'click';
                }
                break;
            case 'password':
            case 'textfield':
            case 'number':
            case 'tel':
            case 'textarea':
                $element['#ajax']['event'] = 'blur';
                break;
            case 'radio':
            case 'checkbox':
            case 'select':
            case 'date':
                $element['#ajax']['event'] = 'change';
                break;
            case 'link':
                $element['#ajax']['event'] = 'click';
                break;
            default:
                return $element;
        }
    }
    // Attach JavaScript settings to the element.
    if (isset($element['#ajax']['event'])) {
        // By default, focus should return to the element focused prior to the
        // execution of AJAX commands within event listeners attached to the blur
        // event. This behavior can be explicitly overridden if needed.
        if (!isset($element['#ajax']['refocus-blur'])) {
            // The change event on text input types is triggered on blur.
            $text_types = [
                'password',
                'textfield',
                'number',
                'tel',
                'textarea',
                'machine_name',
            ];
            if ($element['#ajax']['event'] === 'blur' || $element['#ajax']['event'] === 'change' && in_array($element['#type'], $text_types)) {
                $element['#attributes']['data-refocus-blur'] = "true";
            }
        }
        $element['#attached']['library'][] = 'core/internal.jquery.form';
        $element['#attached']['library'][] = 'core/drupal.ajax';
        $settings = $element['#ajax'];
        // Assign default settings. When 'url' is set to NULL, ajax.js submits the
        // Ajax request to the same URL as the form or link destination is for
        // someone with JavaScript disabled. This is generally preferred as a way to
        // ensure consistent server processing for js and no-js users, and Drupal's
        // content negotiation takes care of formatting the response appropriately.
        // However, 'url' and 'options' may be set when wanting server processing
        // to be substantially different for a JavaScript triggered submission.
        $settings += [
            'url' => NULL,
            'httpMethod' => 'POST',
            'options' => [
                'query' => [],
            ],
            'dialogType' => 'ajax',
        ];
        if (array_key_exists('callback', $settings) && !isset($settings['url'])) {
            $settings['url'] = Url::fromRoute('<current>');
            // Add all the current query parameters in order to ensure that we build
            // the same form on the AJAX POST requests. For example,
            // \Drupal\user\AccountForm takes query parameters into account in order
            // to hide the password field dynamically.
            $settings['options']['query'] += \Drupal::request()->query
                ->all();
            $settings['options']['query'][FormBuilderInterface::AJAX_FORM_REQUEST] = TRUE;
        }
        // Convert \Drupal\Core\Url object to string.
        if (isset($settings['url']) && $settings['url'] instanceof Url) {
            $url = $settings['url']->setOptions($settings['options'])
                ->toString(TRUE);
            BubbleableMetadata::createFromRenderArray($element)->merge($url)
                ->applyTo($element);
            $settings['url'] = $url->getGeneratedUrl();
        }
        else {
            $settings['url'] = NULL;
        }
        unset($settings['options']);
        // Add special data to $settings['submit'] so that when this element
        // triggers an Ajax submission, Drupal's form processing can determine which
        // element triggered it.
        // @see _form_element_triggered_scripted_submission()
        if (isset($settings['trigger_as'])) {
            // An element can add a 'trigger_as' key within #ajax to make the element
            // submit as though another one (for example, a non-button can use this
            // to submit the form as though a button were clicked). When using this,
            // the 'name' key is always required to identify the element to trigger
            // as. The 'value' key is optional, and only needed when multiple elements
            // share the same name, which is commonly the case for buttons.
            $settings['submit']['_triggering_element_name'] = $settings['trigger_as']['name'];
            if (isset($settings['trigger_as']['value'])) {
                $settings['submit']['_triggering_element_value'] = $settings['trigger_as']['value'];
            }
            unset($settings['trigger_as']);
        }
        elseif (isset($element['#name'])) {
            // Most of the time, elements can submit as themselves, in which case the
            // 'trigger_as' key isn't needed, and the element's name is used.
            $settings['submit']['_triggering_element_name'] = $element['#name'];
            // If the element is a (non-image) button, its name may not identify it
            // uniquely, in which case a match on value is also needed.
            // @see _form_button_was_clicked()
            if (!empty($element['#is_button']) && empty($element['#has_garbage_value'])) {
                $settings['submit']['_triggering_element_value'] = $element['#value'];
            }
        }
        // Convert a simple #ajax['progress'] string into an array.
        if (isset($settings['progress']) && is_string($settings['progress'])) {
            $settings['progress'] = [
                'type' => $settings['progress'],
            ];
        }
        // Change progress path to a full URL.
        if (isset($settings['progress']['url']) && $settings['progress']['url'] instanceof Url) {
            $settings['progress']['url'] = $settings['progress']['url']->toString();
        }
        $element['#attached']['drupalSettings']['ajax'][$element['#id']] = $settings;
        $element['#attached']['drupalSettings']['ajaxTrustedUrl'][$settings['url']] = TRUE;
        // Indicate that Ajax processing was successful.
        $element['#ajax_processed'] = TRUE;
    }
    return $element;
}

---