Start Date	Release Date	Release Versions	PR link	Tracking Link	Stage	Teams
5/20/2019	5/3/2021	ember-source: v3.27.0			Recommended	Framework Learning

Deprecate `disconnectOutlet`

Summary

This RFC deprecates Route#disconnectOutlet because it has no use case given #418.

Motivation

Route#disconnectOutlet is intended to be used in conjunction with Route#render. When we wrote #418 we should have also deprecated Route#disconnectOutlet because it is primarily used to teardown named outlets setup by Route#render. For all intensive this is just an addendum to #418.

Transition Path

The transition path is the same to the one outlined in #418. Since the migration path for the named outlets is to use components, a developer would need to wrap the component in a conditional if they want to control the destruction.

Given:

// app/routes/checkout.js

class CheckoutRoute extends Route {
  // ...

  @action
  showModal() {
    this.render('modal', {
      outlet: 'modal',
      into: 'application'
    });
  }

  @action
  hideModal() {
    this.disconnectOutlet('modal');
  }
}

{{! app/templates/checkout.hbs}}

<button {{action 'showModal'}}>Show Modal</button>
<button {{action 'closeModal'}}>Close Modal</button>

{{! app/templates/application.hbs}}
{{outlet "modal"}}

<main>
  {{outlet}}
</main>

This can transitioned to:

// app/controller/checkout.js

class CheckoutController extends Controller {
  // ...
  @tracked isModalOpen = false;

  init() {
    super.init();
    this.modalElement = document.getElementById('modal');
  }

  @action
  showModal() {
    this.isModalOpen = true;
  }

  @action
  closeModal() {
    this.isModalOpen = false;
  }
}

{{! app/templates/checkout.hbs}}

<button {{action 'showModal'}}>Show Modal</button>
<button {{action 'closeModal'}}>Close Modal</button>

{{#if this.isModalOpen}}
  {{#in-element this.modalElement}}
    <Modal />
  {{/in-element}}
{{/if}}

{{! app/templates/application.hbs}}
<div id="modal"></div>

<main>
  {{outlet}}
</main>

The above example will conditionally append the modal component into div#modal whenever the user toggles the modal.

How We Teach This

Once deprecated, developers will be presented with the following deprecation warning:

"disconnectOutlet" has been deprecated for disconnecting outlets.

This deprecation message will also link to the transition guide. The transition guide will cover how to migrate named outlets to components. In addition, the guides should be updated to remove any usage of these APIs.

Drawbacks

N/A. This addendum to #418.

Alternatives