Flatsome Pjax

Version 3.18 debuts tailored Pjax functionality. If you're unfamiliar with the term, Pjax stands for "PushState Ajax." In simpler terms, it's a brilliant combination that facilitates ajax-driven navigation on your website. The result? A user experience that feels incredibly smooth, almost like navigating & filtering within a native application. Beyond mere rapid transitions, it refines the overall navigation and filtering experience.

This feature is currently in experimental phase; given the vast WordPress ecosystem, changes and refinements may occur as we gather more feedback and insights. Everything related to how it works or how it is implemented is subject to change.

Mentioned actions or events prefixed with experimental will change when phasing out.

Out of the box

To get started, head over to the settings section Advanced → Content Delivery. Activating any AJAX-related options here will enable the Pjax feature for that specific part.

Customizing with the 'experimental_flatsome_pjax' filter

If you've got a specific vision for your website's navigation or want to enable it on certain links, the experimental_flatsome_pjax filter has got your back.

Utilizing the filter grants unparalleled flexibility, empowering developers to shape and optimize the Pjax experience precisely to their needs. Customize to your heart's content and, as an illustration, here's how you can Pjaxify the WooCommerce's My Account dashboard links.

And ... 🚀 yes, it's really that simple!

Add selectors and processing elements conditionally if you want precise control over where Pjax loads and activates. If not added conditionally it will load & activate globally (which you may want in specific use cases).

<?php
add_filter( 'experimental_flatsome_pjax', function ( $args ) {
// Only apply if we are on the WooCommerce account page.
if ( is_woocommerce_activated() && is_account_page() ) {
$args['entries'][] = [
// Target dashboard nav links.
'selectors' => [ '.woocommerce-MyAccount-navigation-link a' ],
// Specify the element to show overlay/processing during Pjax operation.
'processing_elements' => [ '.woocommerce-MyAccount-content' ],
];
}
return $args;
} );
view raw functions.php hosted with ❤ by GitHub

Some explanation of parameters that can be set and what they are used for.:

<?php
$args['entries'][] = [
// 'selectors' is an array that specifies the CSS selectors for the elements that will trigger the PJAX request when clicked.
'selectors' => [ '#container .pagination a' ],
// 'elements' is an array that specifies the CSS selectors for the elements that will be replaced with the new content fetched by the PJAX request.
// If this is omitted, the elements specified in '$args['elements']' will be used.
'elements' => [ '#container' ],
// 'processing_elements' is an array that specifies the CSS selectors for the elements that will show a loading indicator while the PJAX request is being processed.
// If this is omitted, the elements specified in '$args['processing_elements']' or the entry elements (if provided) will be used as processing elements.
'processing_elements' => [
'#container' => [
// 'style' specifies the style of the loading indicator. In this case, 'spotlight' is used.
'style' => 'spotlight',
// 'position' specifies the position of the loading indicator. In this case, 'sticky' is used.
'position' => 'sticky',
],
],
// 'scroll_to' specifies the CSS selector for the element that the page will scroll to after the PJAX request is completed.
// If this is omitted, the element specified in '$args['scroll_to']' will be used.
'scroll_to' => '#container',
];
view raw functions.php hosted with ❤ by GitHub

Points to note

This feature is geared towards elevating the user experience. However, there are certain aspects to be mindful of:

  • Select2 dropdowns: Is currently not supported.
  • Plugins JS: If you have scripts linked to specific plugins, they might need a reinitialization after a Pjax refresh on the new content loaded. The experimental-flatsome-pjax-request-done JS event is triggered on the body when a request is completed.

    • jQuery(document.body).on('experimental-flatsome-pjax-request-done', function (event, res, url) {
    console.log('Flatsome Pjax request done!', res, url)
    // Re-attach or re-init some JS here.
    })
    view raw index.js hosted with ❤ by GitHub

Requirements

  • 3.19.0 or greater

Related Articles