{% ajaxPartial %}

The {% ajaxPartial %} tag renders partial contents on the page and includes support for AJAX handlers, self-updating and short update syntax. This is commonly referred to as a self-updating partial.

{% ajaxPartial "contact-form" %}

The partial contents are wrapped with a specific HTML tag on the first load only. Subsequent updates of the partial via AJAX do not include the wrapper tag.

<div data-ajax-partial="contact-form">
    ... Contents go here ...
</div>

# Short Update Syntax

When an AJAX partial is used, you no longer need to specify a selector to update it. Just pass true to the data attributes API when using the data-request-update attribute.

<button
    data-request="onRefresh"
    data-request-update="{ contact-form: true }">
    Refresh
</button>

You may also update the partial from inside itself using _self as the partial name.

<button
    data-request="onRefresh"
    data-request-update="{ _self: true }">
    Refresh
</button>

You may also pass the ^ symbol to prepend and the @ symbol to append content to the container instead of replacing it.

<button
    data-request="onRefresh"
    data-request-update="{ _self: '@' }">
    Append
</button>

# Lazy Loading Partials

The {% ajaxPartial %} accepts a lazy attribute that will defer rendering the content until the page loads.

{% ajaxPartial "posts" lazy %}

The lazy body attributes allow specifying the initial content before loading, followed by the {% endpartial %} tag.

{% ajaxPartial 'posts' lazy body %}
    <p>Loading posts...</p>
{% endpartial %}

# Calling AJAX Handlers

When calling an AJAX handler from inside an AJAX partial, a capturing page life cycle is triggered that enables the use of AJAX handlers within the requested partials.

The following example shows how to submit a simple contact form using a self-updating partial.

description = "Self Updating Partial"
==
<?
function onSubmitContactForm()
{
    $this['submitted'] = true;
}
?>
==
{% if submitted %}
    <p>Thank you for contacting us!</p>
{% endif %}
<button
    data-request="onSubmitContactForm"
    data-request-update="{ _self: true }">
    Submit
</button>

Partials that use CMS components will also have their AJAX handlers made available.

[contactForm]
==
<button
    data-request="contactForm::onSubmit"
    data-request-update="{ _self: true }">
    Submit
</button>