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 -->
<button
    data-request="onRefreshTime"
    data-request-update="mytime: '#myDiv'">
    Go
</button>

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.

• Use $this[] inside a page or layout PHP section.
• Use $this->page[] inside a component class.
• Use $this->vars[] in the backend area.

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

#Handling JavaScript in partials

The AJAX framework writes partial updates by modifying the innerHTML property of the partial that is being updated. Due to the security measures implemented in most browsers, no <script> tags that are written in this manner will execute. This means that you cannot embed <script> tags in your partials.

If you would like to allow JavaScript to manipulate your partial after being loaded, you should add an external JavaScript file loaded through your controller or widget through the addJs() method and listen to the event that fires when AJAX requests complete.

This will be slightly different depending on whether you are using the original AJAX framework or using Snowboard.

#jQuery example

(function ($) {
    $(document).on('render', function () {
        // ... Your code to manipulate the partial
    });
})(jQuery);

#Snowboard example

Snowboard.on('ajaxDone', () => {
    // ... Your code to manipulate the partial
});

NOTE: Both examples above will fire on any AJAX request being completed. You must refine your code to focus on the specific partial you wish to target by, for example, checking that a particular element with an ID or class exists. You can also use the AJAX Framework JS API or Snowboard JS API to attach to a particular element.