Warning about losing unsaved changes in Ember Octane

06 February 2020

I recently held an Ember Octane training and while preparing for it, I implemented a pattern that I thought worthwhile to share.

The all-powerful router service

One of the most underappreciated (is that a word?) pieces of Ember's architecture, in my opinion, is the router service. While working on different things, I've found myself reaching for it and finding it perfectly fit my needs. One such thing is route events, routeDidChange and routeWillChange that are fired on the service each time a transition is complete or about to begin.

You can handle these events on the route, too, but just as with other router-related features (like the transitionTo method), I reckon using the router service makes it easier to teach and remember. transitionTo is a great example: you should call it as this.transitionTo from routes, this.transitionToRoute from controllers and you can't call it in any way from components. Injecting the router service and calling this.router.transitionTo is a uniform way to launch a transition from everywhere.

Are you sure you want to lose your changes?

The particular example we'll look at is navigating away from a page that contained unsaved changes – starting to type out the name of a new band and clicking a link before saving. That that'd destroy the component that contained the name and is likely something we'd like to warn the user about. The routeWillChange event gives us the possibility to call off the transition. Let's see how.

A very basic form would look on screen as follows:

And would have the following source:

 // app/components/new-band-input.js
 import Component from '@glimmer/component';
 import { action } from '@ember/object';
 import { tracked } from '@glimmer/tracking';
 
 export default class NewBandInputComponent extends Component {
   @tracked name = '';
 
   get isNameEmpty() {
    return this.name === '';
  }

  @action
  cancel() {
    this.router.transitionTo('bands');
  }

  @action
  updateName(event) {
    this.name = event.target.value;
  }
}

 {{!-- app/templates/new-band-input.hbs --}}
 <div class="w-full flex" ...attributes>
   <input
     type="text"
     class="..."
     value={{this.name}}
     {{on "input" this.updateName}}
   />
   <button
    type="button"
    class="..."
    disabled={{this.isNameEmpty}}
    {{on "click" (fn @onAdd this.name)}}
  >
    Add
  </button>
  <button
    type="button"
    class="..."
    {{on "click" this.cancel}}
  >
    Cancel
  </button>
</div>

At this point nothing prevents losing unsaved changes when the user leaves before hitting the Add button.

Adding the guard

Let's now add the guarding code, leveraging the willRouteChange event.

 // app/components/new-band-input.js
 + import { inject as service } from '@ember/service';
 
 export default class NewBandInputComponent extends Component {
   @tracked name = '';
 +  @service router;
 
 +  constructor() {
 +    super(...arguments);
+    this.addExitHandler();
+  }

  get isNameEmpty() {
    return this.name === '';
  }

+  addExitHandler() {
+    this.router.on('routeWillChange', this, this.confirm);
+  }
+
+  removeExitHandler() {
+    this.router.off('routeWillChange', this, this.confirm);
+  }
+
+  confirm(transition) {
+    if (this.name) {
+      this.confirmExit(transition);
+    }
+  }
+
+  confirmExit(transition) {
+    let leave = window.confirm('You have unsaved changes. Are you sure?');
+    if (!leave) {
+      transition.abort();
+    }
+  }
+
+  willDestroy() {
+    this.removeExitHandler();
+  }

  @action
  cancel() {
    this.router.transitionTo('bands');
  }

  @action
  updateName(event) {
    this.name = event.target.value;
  }
}

We add a route event listener in addExitHandler. We have to make sure we also tear down the event listener when the component is no longer rendered on screen, so we have to call removeExitHandler in the right handler. We also have to make sure we're calling the exact same function (with the same this) when deregistering the event listener. Extracting the function to the confirm method makes this possible.

In confirmExit, we throw up the ugly, default confirm dialog that asks the user to confirm their intent to leave. If they realize they don't want to lose their changes, we stop the transition from happening so we stay on the same page. The willDestroy hook is the classic way to de-register event listeners and even Glimmer components have it.

Getting the timing of deregistering our event listener correctly

That works but there's a slight problem. Clicking the Add button calls the passed in onAdd function which saves the band on the back-end and then transitions to a new route. That means that our event listener fires once more and brings up the dialog – which is not something we want:

A possible way to work around that is to remove the event listener when the Add button is clicked and before the passed in onAdd is called. That's a small change:

 {{!-- app/templates/new-band-input.hbs --}}
 <div class="w-full flex" ...attributes>
   {{!-- ... --}}
   <button
     type="button"
     class="..."
     disabled={{this.isNameEmpty}}
 -    {{on "click" (fn @onAdd this.name)}}
 +    {{on "click" this.add}}
  >
    Add
  </button>
  <button
    type="button"
    class="..."
    {{on "click" this.cancel}}
  >
    Cancel
  </button>
</div>

 // app/components/new-band-input.js
 export default class NewBandInputComponent extends Component {
   // ...
 +  @action
 +  add() {
 +    this.removeExitHandler();
 +    this.args.onAdd(this.name);
 +  }
 
  @action
  cancel() {
    this.router.transitionTo('bands');
  }
}

Remove event listeners once – and exactly once

That works but we now have to make sure we don't attempt to remove the same event listener twice – both from add and willDestroy. Trying to do makes Ember unhappy and scold us.

 // app/components/new-band-input.js
 export default class NewBandInputComponent extends Component {
   @tracked name = '';
   @service router;
   hasRemovedExitHandler = false;
 
   // (...)
   removeExitHandler() {
 +    if (!this.hasRemovedExitHandler) {
+      this.router.off('routeWillChange', this, this.confirm);
+      this.hasRemovedExitHandler = true;
+    }
  }
}

All right, hang on, we're almost there.

Clicking around and trying different scenarios reveals one more error. If we hit Cancel on the modal dialog, indicating we want to stay and not lose our changes, our app will bring up the dialog again and again until we give up, close the tab, and go for a walk.

A canceled transition is also a transition

Turns out that if we call transition.abort on a transition, that transition will be re-fired and our event handler duly catches it. That's what makes the infinite loop infinite (and a loop) so we should prevent that from happening. Happily, that's as simple as checking if the transition is aborted and only reacting to non-aborted ones:

 // app/components/new-band-input.js
 export default class NewBandInputComponent extends Component {
   @tracked name = '';
   @service router;
   // (...)
   confirm(transition) {
 +    if (transition.isAborted) {
 +      return;
 +    }

    if (this.name) {
      this.confirmExit(transition);
    }
  }
  // (...)
}

With that final fix, we have a fully working solution.