Cookbook: how to embed Liquid Fire into your Ember app

In order to embed Liquid Fire into your application, there are a very few steps take. Since you are here, you probably already followed the installation guide. Now it is time to setup your transitions.

1. Setup transitions

The first step is to create the file transitions.js file next to router.js in the applications root folder, so you get app/transitions.js. Below you will find an example what the content of such file may look like.

export default function () {
  this.transition(
    this.fromRoute('index'),
    this.toRoute('posts'),
    this.use('toLeft'),
    this.reverse('toRight'),
  );
}

Here we have chosen to create a swipe transition, from right to left, when the user moves from the index route to the posts route. The reverse call indicates what should happen when the user goes moves from the posts to the index route: the swipe should be into the other direction. There many more transitions included by default.

2. Replace outlets in your templates

Now we have defined our transitions, the next step is to replace Embers native {{outlet}} in your template files. You should replace it with the outlet component by Liquid Fire: <LiquidOutlet />. It is most likely that you will find this {{outlet}} in your application template file. So now your app/templates/application.hbs might look like this.

<nav>
    <ul>
        <li><LinkTo @route="index">Index</LinkTo></li>
        <li><LinkTo @route="posts">Posts</LinkTo></li>
    </ul>
</nav>

<main>
    <LiquidOutlet />
</main>

3. Create a transition to another route

When you create a {{#link-to}} from the index route to the posts route, and click it, it will now show you the beautiful transitions that you created in your transitions.js file. The example template from the previous step already includes such a {{#link-to}}. That's it, you now configured Liquid Fire!

4. Transitions for nested routes

Since you are done with the first steps, you are ready for some more action! What if I want to create a transition to a nested route? This requires a little extra step! Suppose our app/routes.js looks as follows.

import EmberRouter from '@ember/routing/router';
import config from 'docs/config/environment';

export default class Router extends EmberRouter {
  location = config.locationType;
}

Router.map(function () {
  this.route('posts', function () {
    this.route('new');
  });
});

We now want to create a transition when the user clicks on a button to create a new post. First we add another transition into our app/transitions.js from the first step.

export default function () {
  this.transition(
    this.fromRoute('index'),
    this.toRoute('posts'),
    this.use('toLeft'),
    this.reverse('toRight'),
  );
  this.transition(
    this.fromRoute('posts.index'),
    this.toRoute('posts.new'),
    this.use('crossFade'),
    this.reverse('crossFade'),
  );
}

Next, place the content template from app/templates/posts.hbs into app/templates/posts/index.hbs, if you have not done that already. And in app/templates/posts.hbs we place a new liquid outlet component, so the file looks like this.

<LiquidOutlet />

Finally, create a button in your app/templates/posts/index.hbs route that links to the posts.new route. And click it. You will now see (another build-in) cross-fade transition!

Remember, you will have to include a <LiquidOutlet /> in any nested route's master template. Otherwise, there will be no transition visible. This is how Ember works. A nested master template contains {{outlet}} by default and you should overwrite it with a <LiquidOutlet />. But that is easy, right?