{% ajaxPartial %}
This tag extends the {% partial %}
Twig tag.
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>