Edit on GitHub

Updating Partials

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. The following code renders the mytime partial inside the #myDiv element on the page after calling the onRefreshTime event handler.

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

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

<!-- Attributes API -->
    data-request-update="mytime: '#myDiv'">

The JavaScript API uses the update configuration option:

// JavaScript API
$.request('onRefreshTime', {
    update: { mytime: '#myDiv' }

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'

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.

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.

'folder/append': '@#myDiv'

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

'folder/append': '^#myDiv'

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 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')

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

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 }}

Keep informed

Sign up to our newsletter to receive updates on Winter CMS releases, new features in the works, and much more.
We'll never spam or give this address away.

Latest blog post

Winter: 16 Months Later

Published July 14, 2022
With the first year of Winter behind us, let's take a look at what we were able to achieve in 2021.

View this post Read all posts

Latest Winter CMS release


Released October 20, 2022
14 UX/UI Improvements, 25 API Changes, 33 Bug Fixes, 4 Security Improvements, 5 Translation Improvements, 1 Performance Improvement, 2 Community Improvements, 2 Dependencies, 0 New Contributors * @cstorus made their first contribution in https://github.com/wintercms/winter/pull/616 * @simonmannsfeld made their first contribution in https://github.com/wintercms/winter/pull/623 * @quangtrongonline made their first contribution in https://github.com/wintercms/winter/pull/636 * @nathanlesage made their first contribution in https://github.com/wintercms/winter/pull/665 * @vllvll made their first contribution in https://github.com/wintercms/winter/pull/669 * @robertalexa made their first contribution in https://github.com/wintercms/winter/pull/668 * @iamyigitkoc made their first contribution in https://github.com/wintercms/winter/pull/624 * @hecc127 made their first contribution in https://github.com/wintercms/winter/pull/682 * @prsuhas made their first contribution in https://github.com/wintercms/winter/pull/723

View details View all releases