Animation matching with the JS plugin

[wwdboer]

Hi, today i've been reading the docs and trying out Swup and i really like it! The only thing i'm not sure about is how to handle the matching of animations with the JS plugin.

From what i've read this is only based on the to and from urls, or an animation name as data-swup-animation attribute on a link.

Let's say i've an about page on my website and i've made a nice gsap animation that runs when you go from any page to /about/. Now someone changes the url of the about page to /about-us/ in the cms, the transition isn't working anymore.

Do you have a suggestion how to handle this? Is there maybe a way to parse the html of the next page to get a body class or data-attribute to determine the right transition animation? I think the page:load hook is too late and the visit:start hook too early.

P.S. I hope this is the right place to ask this question :)

[hirasso]

Great question! Swup is designed to optimize the perceived performance of a website by starting the loading process of the next page at the same time as the animation to that page. Whichever finishes last, will trigger the page:view hook. Because of this, the only way to reliably determine where you are currently navigating towards is the URL. On visit:start, swup doesn't know anything about the next page, yet. On page:load, the animation has already started.

If your URLs might change, my suggestion would be to have a central place in your CMS where you store references to your special pages. Then, you would render these pages as a JS global in your HTML and use that for the instantiation of JS plugin.

In your HTML head you could do something like this:

<!-- dynamically generated list of URLs
<script>
const animationRoutes = {
  about: '/about-us/',
  foo: '/bar/'
  // ...
}
</script>

And then access this route in your main js file:

const swup = new Swup({
  plugins: [
    new SwupJsPlugin({
      animations: [
        {
          from: '(.*)', // matches any route
          to: window.animationRoutes.about, // to the about page
          out: done => done(), 
          in: done => done() 
        },
        {
          from: '(.*)', // matches any route
          to: window.animationRoutes.foo, // to the foo page
          out: done => done(), 
          in: done => done() 
        },
        // ...
        {
          from: '(.*)',
          to: '(.*)', 
          out: done => done(),
          in: done => done()
        }
      ]
    })
  ]
});

[daun]

Agree with @hirasso that outputting a JSON array of URLs from the backend is the way to go for matching specific pages, especially in multi-language setups. Easy to do and predictable.

There's an alternative approach that doesn't require knowing the urls in advance, but it's a bit involved:

1. Tell swup to wait for the new page to load before running the animation — which as mentioned by @hirasso is detrimental to perceived performance, but sometimes you gotta do what you gotta do :)
2. In JS Plugin, only define a single animation that matches all routes (from (.*) and to (.*))
3. Inside the animation callback, check the new page's content to determine what type of page you're dealing with, e.g. by checking a data-template attribute on the body element.

const swup = new Swup({
  hooks: {
    'visit:start': (visit) => {
      // Wait for next page to load before animating
      visit.animation.wait = true
    }
  },
  plugins: [
    new SwupJsPlugin({
      animations: [
        {
          from: '(.*)',
          to: '(.*)', 
          out: (done, { visit }) => {
            const from = document.body.dataset.template
            const to = visit.to.document.body.dataset.template
            if (from === 'home' && to === 'about') {
              // handle about page animation
            } else {
              // handle all other animations
            }
          },
          in: (done, { visit }) => {
            const from = document.body.dataset.template
            const to = visit.to.document.body.dataset.template
            if (from === 'home' && to === 'about') {
              // handle about page animation
            } else {
              // handle all other animations
            }
          }
        }
      ]
    })
  ]
})

[wwdboer]

Thanks for the detailed explanations! I am going to play around with this and see what works best for me.