Series: Animations with Liquid FIre

Liquid Fire-Matchers and the Transition Map

Published on Mar 11, 2016

The Transition Map is the set of instructions stored in transitions.js that determine when and how each animation runs. We’ve been using it already, but in this episode we dig deeper.

We’ll first go over the two top-level functions of the Transition Map, then look at each of the available matchers that we can use to specify where our transitions will be used.




In the last three episodes, we’ve been going over the template helpers of Liquid Fire. In doing that, we’ve been using lots of transitions as defined in the transition map. However, we haven’t done a rigorous overview of what these are. So that’s what we’re going to do this time.

So in the transition map, which is what you put into transitions.js, there are two top level functions. The first is transition. That’s what we’ve been using. And so a transition consists of a use statement, and you’ll see that each of these does have a use statement, and then it says one or more constraints. And a constraint is something like fromRoute or hasClass.

The second top level function is setDefault. And so it’s linking to something called Velocity.defaults. Now velocity.js is the JavaScript library that’s underlying Liquid Fire. It’s what does a lot of the animations for us. And Liquid Fire is a really nice DSL on top of that. So we can set a lot of default options. You’ll notice we’ve used duration before. And so these are things that you can also set in the use property of the transition.

So here are a bunch of the options with their defaults, and if you want to change those defaults you can, and if you want to look at the documentation for them, it’s all here. However in this video, we’re not going to go over Velocity.js. Instead, we’re going to look at all the matchers that we can put into this transition map. We’ll start with the route and model constraints.

So fromRoute and toRoute will probably be the ones they use most often, at least at the beginning, and they’re very well-named, very self-explanatory. So you can have either one or both. You can see here that in this first one, it doesn’t matter where we’re going as long as we’re coming there from the monsters.index. Whereas in this transition, we have to go from the showRoute to the editRoute, or vice versa.

withinRoute is... well, I’m not really sure how to use this, so I spent a lot of time trying to make the thing that we ended up putting in the liquid-bind, this transition. I spent a lot of time trying to make that work with withinRoute, but it doesn’t. So I guess it might be good for query parameters... I’m not sure. And the same thing applies to the fromModel, toModel, and betweenModels. I can’t find them in any of these examples.

And I tried it here. Here I’m going to log out whenever the fromModel is triggered. So I thought maybe this would be how we would accomplish this without the liquid-bind. But it’s not logging anything. It does however log whenever we go from the edit or the show route to a different route. So I’m not exactly sure on the use case of this, but the syntax if you’re curious is to pass it a function, and first argument is the oldModel, second is the newModel, and that’s reversed if you do toModel. And then you return a Boolean that says whether you’re going to do this transition or not.

Next up is matching by value. Value constraints only apply to liquid-if and the liquid-bind helpers because they’re the ones that are passed values. We can see that happening here in this liquid-if. So it’s passed the isHighLevel Boolean. Then in our transition map, we can see this is the transition that’s based on that liquid-if, and we’re using the toValue method. So the toValue constraint, one of the things it can be fed is a Boolean. For the if helper that’s all it can be fed, or all it really makes sense to feed it. And so here it can be true or false, and remember this determines the directionality of the if statement.

The liquid-bind helper on the other hand is fed more than just Booleans. Here it’s being fed an entire model. So that means the fromValue and toValue for a liquid-bind can be more complex. Specifically in addition to being a Boolean, it can also be a simple string or a number, it can be null which will match null or undefined, or it can be a regular expression or a function. The function is the most complex, so that’s the one we’ll spend a little bit more time on.

So the function looks like this. It takes the value as the argument, and then the return value will be a Boolean which tells you whether or not you’re going to run that transition. One cool use case for this done halfway here is when you’re going to a lower number, you go one way, and when you’re changing to a higher number, you go the other way, so it looks like it’s all on one number line. You can accomplish that with value constraints.

So the next type of constraint is media query. When I first read about these, I imagined that it would animate when I did this, such as when it bounces between... it’s right there. But what it actually is is it’ll change what animations are displaying based on what size the screen currently is. So if you want things to look differently on mobile, this is where you go.

Next are the constraints based on DOM context. We’ve already seen hasClass, and we’ve used hasClass in two of our transitions for our if statement and for our liquid-bind. In this particular case, we’re matching on the class liquid-monster, and that class is on our liquid-bind template helper.

But hasClass isn’t the only DOM constraint. There’s matchSelector which matches based on CSS selectors. So it can be a class, it can be an id, or any of the other more obscure things. So if the selector matches, then the transition is a go. childOf is similar, but it’s checking the parent rather than the element itself. Remember we used this in one of our previous episodes. Lastly we have inHelper. And what it does is it specifies it to one of the four different template helpers. Here we’re using liquid-if as the example.

Then in our last set of constraints, we have InitialRender. So by default it’s not animating during the InitialRender, but you can make it do that. You can make it happen only on the InitialRender, or you can do it during the default as well as the InitialRender.

So that’s our overview of the transition map, specifically with the matching constraints that you can have on the various transitions. I hope to see you next time when we talk more about the animations, specifically more advanced animations like creating an explode animation. I’ll see you then.

Animations with Liquid FIre

Subscribe to our mailing list