Page Transitions

This extension is using the pjax technique to load new pages. It will load the content via ajax and animate it if needed. This will make your website feel much faster and smoother. To animate the pages, you can choose between CSS and GSAP. For GSAP, you can even connect an already created timeline using the Bricksforge Panel. As library, we are using swup.

Page Transitions are included since Bricksforge 2.0.0.

Understanding pjax

pjax stands for “pushState + AJAX”. It’s a technique used in web development to load new content into a page without a full page reload, making for a smoother user experience. pjax does this by fetching new content via AJAX and then using the pushState method to update the browser’s URL and history, so that users can still use the back and forward buttons as they would expect. This technique offers a faster and more seamless browsing experience compared to traditional full-page loads.

The Challenge

For WordPress websites, the use of pjax can introduce complexities, especially since WordPress plugins and themes might load scripts conditionally based on the specific page or post type. Here’s what this means:

• Script Handling: When using pjax in a WordPress environment, it’s crucial to ensure that any necessary JavaScript files are loaded and initialized correctly on pjax content replacement. If not handled right, scripts might not work as intended after a pjax content load.
• Dependency Management: WordPress enqueues scripts with dependencies. If a pjax-loaded content requires a script that hasn’t been loaded yet because it wasn’t needed on the initial page, this can cause functionality to break.
• Admin Bar: WordPress includes elements like the admin bar based on user roles. With pjax, these dynamic elements could potentially be affected if not handled correctly.
• Inline Scripts: Some plugins or themes might add inline JavaScript that’s intended to run when the page loads. With pjax, since a full page load doesn’t occur, these inline scripts might not execute as expected.
• Event Listeners: Scripts that bind event listeners to elements on the initial page might not be bound to new elements fetched via pjax, unless they are re-initialized after the pjax content loads.

Our Way

We searched for a solution that would allow us to use pjax in WordPress without having to worry about the complexities mentioned above. In reality, this won’t be possible without some sort of compromise. The good thing: Because Bricksforge is a plugin for Bricks, we know the environment. We can make sure that Bricks & Bricksforge related scripts are loaded correctly and that the dependencies are met. And we did exactly that.

The Page Transitions functionality should work fine using Bricks & Bricksforge. But what about Third Party Plugins? That’s the compromise. In the Bricksforge settings page, you have the possibility to use a code area to add your custom javascript. This code is fired after the page transition is done. So you can use this to reinitialize the scripts of the third party plugins. So you need to add the compatibility yourself.

Important: We will not provide support in the form of “how do I make plugin XY compatible with pjax” or “Plugin XY is not working while using page transitions”. If you have problems with a plugin, please contact the plugin author and ask for help to re-initialize the plugin scripts on page change.

How to use

Enable Page Transitions

To enable the page transitions, go to the Bricksforge “Extensions” page and enable the “Page Transitions” toggle. Now, you should see a new tab “Page Transitions”.

Configuration

General Options

Containers

The content containers to be replaced on page visits. Usually the <main> element with the content of the page, but can include any other elements that are present across all pages. Defaults to a single container of id #brx-content.

Animation Scope

The elements on which swup will add the animation classes for styling the different phases of the in/out animation. By default, it will add those classes to the html tag. This is great for most use cases and the recommended way to use page transitions.

Link Selector

The link elements that trigger visits. By default, all a elements with an href attribute will receive clicks.

Morph Containers

The Morph Plugin allows you to morph elements from one state to another. If you are using the Morph Plugin, you can define the containers here. The prime use cases are headers and menus on multi-language sites: you might not want to swap these elements out with a transition on each page visit, however you’d still want to update any URLs, labels or classnames when the user switches between languages. Morphed elements will keep their state when a page is visited.

You get more informations abouth the Morph Plugin here: Morph Plugin

Cache

Whether to cache pages after they have been loaded. Defaults to true.

Animation Options

Animation Type

You can choose between CSS and GSAP. If you choose GSAP, you can connect an already created timeline using the Bricksforge Panel or write custom GSAP code.

Animate History Browsing

Whether to animate pages when using the back/forward buttons. Defaults to true.

Animate with CSS

Swup is adding CSS classes on certain events. You can use these classes to animate the page transitions.

Example:

/* Define a transition duration during page visits */
html.is-changing .brf-page-transition {
  transition: opacity 0.3s;
  opacity: 1;
}
/* Define the styles for the unloaded pages */
html.is-animating .brf-page-transition {
  opacity: 0;
}

In this example, we are using the is-changing and is-animating classes to animate the page transitions. The is-changing class is added when a page visit is triggered. The is-animating class is added when the new page is loaded and the old page is unloaded. This code will animate from opacity 0 to 1 during the page visit.

Animate with GSAP (Timeline)

This setting allows you to choose a timeline from the Bricksforge Panel. Just enter the ID of the timeline and it will be connected to the page transitions. If the second “Timeline ID” field is empty, the first timeline will be reversed and played on page exit.

Important: For best results, the “IN” animation should be a “From To”-animation.

Animate with GSAP (Custom)

This setting allows you to write custom GSAP code. You have the possibility to set an “Animation Out” and an “Animation In” timeline. The “Animation Out” timeline will be played on page exit and the “Animation In” timeline will be played on page visit.

Important: For best results, the “IN” animation should be a “From To”-animation.

Routing Options

You can use animations depending on the route. For example, you can use a different animation for the homepage than for the other pages. Just use the “From Route” and “To Route” fields to setup your routes.

Example: If you want to use a different animation for the “test” page, you can use the following settings:

• To Route: /test

/ will be your homepage. If you leave a route field empty, it will be used as wildcard. If “From Route” is empty, it means: “From any route”. If “To Route” is empty, it means: “To any route”.

Play on initial page load

If you want to play the animation on the initial page load, you can enable this setting.

Compatibility

This tab includes a code area where you can add your custom javascript. This code is fired after the page transition is done. So you can use this to reinitialize the scripts of the third party plugins.

Reminder: We will not provide support in the form of “how do I make plugin XY compatible with pjax” or “Plugin XY is not working while using page transitions”. If you have problems with a plugin, please contact the plugin author and ask for help to re-initialize the plugin scripts on page change.

Common Issues

Lightbox is not working

If you are using the lightbox functionality of Bricks to open images, this will cause issues with the default configuration. That’s because the default link selector is a[href]. This means that every link with an href attribute will be handled by the page transitions. This includes the lightbox links. To fix your lightbox, you need to change the link selector to a[href]:not(.bricks-lightbox). This way you exclude the lightbox links from the page transitions and the lightbox will work as expected.