menu-btn

Updating Partials

Updating Partials

Learn more about the updating your content dynamically.

When a handler executes it may prepare partials that are updated on the page, either by pushing or pulling, which can be rendered with some supplied variables.

# Pulling Partial Updates

The client browser may request partials to be updated from the server when it performs an AJAX request, which is considered pulling a content update.

Using the {% partial %} tag, the following code renders the mytime partial inside a #myDiv element on the page when calling the onRefreshTime event handler.

<div id="myDiv">
    {% partial 'mytime' %}
</div>

The data attributes API uses the data-request-update attribute.

<!-- Attributes API -->
<button
    data-request="onRefreshTime"
    data-request-update="{ mytime: '#myDiv' }">
    Go
</button>

The JavaScript API uses the update configuration option:

// JavaScript API
oc.request('#mybutton', 'onRefreshTime', {
    update: { mytime: '#myDiv' }
});

# Self-Updating Partials

The {% ajaxPartial %} tag is dedicated to rendering AJAX partials.

{% ajaxPartial 'mytime' %}

When using this tag, the contents are wrapped in a container for you, so you can update the partial by name alone. Simply pass the true value instead of a container selector.

<button
    data-request="onRefreshTime"
    data-request-update="{ mytime: true }">
    Go
</button>

You may also use the partial name _self for updating a partial from within itself.

{ _self: true }

See the AJAX Partial Twig Tag article to learn more about the {% ajaxPartial %} tag.

# Global Partial Updates

In some cases, such as with flash messages, you may wish to include a specific partial update with every response. To merge an update definition with every AJAX request, add the ajax-request-update meta tag in the head section of the page, and set the content attribute to an update definition.

<head>
    <meta name="ajax-request-update" content="{ flash-messages: true }" />
</head>

# Update Definition

The definition of what should be updated is specified as a JSON-like object where:

  • the left side (key) is the partial name
  • the right side (value) is the target element to update

The following will request to update the #myDiv element with mypartial contents.

{ mypartial: '#myDiv' }

The selector must start with a # or . character to be valid.

Multiple partials are separated by commas.

{ firstpartial: '#myDiv', secondpartial: '#otherDiv' }

If the partial name contains a slash or a dash, it is important to 'quote' the left side.

{ 'folder/mypartial': '#myDiv', 'my-partial': '#myDiv' }

The target element will always be on the right side since it can also be a HTML element in JavaScript.

{ 'folder/mypartial': document.getElementById('myDiv') }

# Appending and Prepending Content

If the selector string is prepended with the @ symbol, the content received from the server will be appended to the element, instead of replacing the existing content.

If the selector string is prepended with the ^ symbol, the content will be prepended instead.

{ 'folder/append-partial': '@#myDiv' }

{ 'folder/prepend-partial': '^#myDiv' }

Alternatively, you may add the data-ajax-update-mode attribute to the target element.

<div id="myDiv" data-ajax-update-mode="append"></div>

<div id="myDiv" data-ajax-update-mode="prepend"></div>

# Using Custom HTML Selectors

If the selector string begins with an = symbol, then you can use any custom HTML selector to target an element.

{ 'folder/append': '=[data-field-name="address"]' }

# Pushing Partial Updates

Comparatively, AJAX handlers can push content updates to the client-side browser from the server-side. To push an update the handler returns an array where the key is a HTML element to update (using a simple CSS selector) and the value is the content to update.

The key name must start with an identifier # or class . character to trigger a content update.

The following example will update an element on the page with the id myDiv using the contents found inside the partial mypartial. The onRefreshTime handler calls the renderPartial method to render the partial contents in PHP.

function onRefreshTime()
{
    return [
        '#myDiv' => $this->renderPartial('mypartial')
    ];
}

# Passing Variables to Partials

Depending on the execution context, an AJAX event handler makes variables available to partials differently.

These examples will provide the result variable to a partial for each context:

// From page or layout PHP code section
$this['result'] = 'Hello world!';

// From a component class
$this->page['result'] = 'Hello world!';

// From a backend controller or widget
$this->vars['result'] = 'Hello world!';

This value can then be accessed using Twig in the partial:

<!-- Hello world! -->
{{ result }}

← Data Attributes API →