From a7a581d275dac1c9d94d3c110381f701f21bd641 Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Wed, 19 Dec 2018 14:08:32 -0500 Subject: [PATCH 1/5] Deprecate Route Render APIs --- text/0000-deprecate-route-render-methods.md | 72 +++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 text/0000-deprecate-route-render-methods.md diff --git a/text/0000-deprecate-route-render-methods.md b/text/0000-deprecate-route-render-methods.md new file mode 100644 index 0000000000..68bac6a2fd --- /dev/null +++ b/text/0000-deprecate-route-render-methods.md @@ -0,0 +1,72 @@ +- Start Date: 2018-19-12 +- RFC PR: (leave this empty) +- Ember Issue: (leave this empty) + +# Summary + +This RFC proposses the deprecation of [`Route#render`](https://emberjs.com/api/ember/3.6/classes/Route/methods/render?anchor=render), [`Route#renderTemplate`](https://emberjs.com/api/ember/3.6/classes/Route/methods/render?anchor=renderTemplate) and named `{{outlet}}` APIs. + +# Motivation + +These APIs are largely holdovers from a time where components where not as prominent in your typical Ember application. While they are still documented, these APIs created an interesting coupling between the `Route` and the template. These APIs are also prone to breaking conventional naming conventions, which can lead to confusion for developers. + +# Transition Path + +The migration plan here is to just move to components for all the use cases you would use theses APIs for. For example, there was a time when you would do something like the following if you wanted to have a master-detail view for a shopping app. + +```js +Ember.Route.extend({ + // ... + + renderTemplate() { + this.render('cart', { + into: 'checkout', + outlet: 'cart', + controller: 'cart' + }) + } +}) +``` + +```hbs +{{! checkout.hbs}} +
+ {{outlet}} +
+ +``` + +This would tell Ember to render `cart.hbs` into `checkout.hbs` at the `{{outlet "cart"}}` and use the `cart` controller to back the `cart.hbs` template. This is pretty confusing pattern and creates this implicit coupling that is spread between the `Route` and template. + +Luckily, we can express this entire concept with components. + +```hbs +{{! checkout.hbs}} +
+ {{outlet}} +
+ +``` + +In the event you were using `model` to derive what to render, you can us the `{{component}}` helper to dynamically render a component. + +# How We Teach This + +This has not been a mainline API for quite some time now. The guides do not mention this functionality at all. It is likely that the majority of Ember applications do not use these APIs. + +# Drawbacks + +The drawback of this is we are saying that the `Route` and the route template of the same name are inherently coupled. In previous versions of Ember this didn't have to be so as long as you implemented `renderTemplate`. + +# Alternatives + +No real alternatives. + +# Unresolved questions + +Optional, but suggested for first drafts. What parts of the design are still +TBD? From ddbf21eaefae946a7e97573fec10334fb104e259 Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Wed, 19 Dec 2018 20:38:16 +0000 Subject: [PATCH 2/5] Update and rename 0000-deprecate-route-render-methods.md to 0418-deprecate-route-render-methods.md (#422) --- ... => 0418-deprecate-route-render-methods.md} | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) rename text/{0000-deprecate-route-render-methods.md => 0418-deprecate-route-render-methods.md} (92%) diff --git a/text/0000-deprecate-route-render-methods.md b/text/0418-deprecate-route-render-methods.md similarity index 92% rename from text/0000-deprecate-route-render-methods.md rename to text/0418-deprecate-route-render-methods.md index 68bac6a2fd..3a1c4770bc 100644 --- a/text/0000-deprecate-route-render-methods.md +++ b/text/0418-deprecate-route-render-methods.md @@ -1,16 +1,18 @@ - Start Date: 2018-19-12 -- RFC PR: (leave this empty) +- RFC PR: https://github.com/emberjs/rfcs/pull/418 - Ember Issue: (leave this empty) -# Summary +# Deprecate Route render APIs + +## Summary This RFC proposses the deprecation of [`Route#render`](https://emberjs.com/api/ember/3.6/classes/Route/methods/render?anchor=render), [`Route#renderTemplate`](https://emberjs.com/api/ember/3.6/classes/Route/methods/render?anchor=renderTemplate) and named `{{outlet}}` APIs. -# Motivation +## Motivation These APIs are largely holdovers from a time where components where not as prominent in your typical Ember application. While they are still documented, these APIs created an interesting coupling between the `Route` and the template. These APIs are also prone to breaking conventional naming conventions, which can lead to confusion for developers. -# Transition Path +## Transition Path The migration plan here is to just move to components for all the use cases you would use theses APIs for. For example, there was a time when you would do something like the following if you wanted to have a master-detail view for a shopping app. @@ -54,19 +56,19 @@ Luckily, we can express this entire concept with components. In the event you were using `model` to derive what to render, you can us the `{{component}}` helper to dynamically render a component. -# How We Teach This +## How We Teach This This has not been a mainline API for quite some time now. The guides do not mention this functionality at all. It is likely that the majority of Ember applications do not use these APIs. -# Drawbacks +## Drawbacks The drawback of this is we are saying that the `Route` and the route template of the same name are inherently coupled. In previous versions of Ember this didn't have to be so as long as you implemented `renderTemplate`. -# Alternatives +## Alternatives No real alternatives. -# Unresolved questions +## Unresolved questions Optional, but suggested for first drafts. What parts of the design are still TBD? From 01af231ad8c1275424eba457f1241469d7b33b77 Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Mon, 7 Jan 2019 10:46:44 -0500 Subject: [PATCH 3/5] Add more examples --- text/0418-deprecate-route-render-methods.md | 185 +++++++++++++++++++- 1 file changed, 180 insertions(+), 5 deletions(-) diff --git a/text/0418-deprecate-route-render-methods.md b/text/0418-deprecate-route-render-methods.md index 3a1c4770bc..8c2d001463 100644 --- a/text/0418-deprecate-route-render-methods.md +++ b/text/0418-deprecate-route-render-methods.md @@ -10,11 +10,15 @@ This RFC proposses the deprecation of [`Route#render`](https://emberjs.com/api/e ## Motivation -These APIs are largely holdovers from a time where components where not as prominent in your typical Ember application. While they are still documented, these APIs created an interesting coupling between the `Route` and the template. These APIs are also prone to breaking conventional naming conventions, which can lead to confusion for developers. +These APIs are largely holdovers from a time where components where not as prominent in your typical Ember application. While they are still documented, these APIs created an interesting coupling between the `Route` and the template. These APIs are also prone to breaking conventional naming conventions, which can lead to confusion for developers. Another issue is that it is unclear how something like this works with route based tree shaking, as there are no strong conventions or direct imports as to what is actually being used. ## Transition Path -The migration plan here is to just move to components for all the use cases you would use theses APIs for. For example, there was a time when you would do something like the following if you wanted to have a master-detail view for a shopping app. +The migration plan here is going to be somewhat situational based on the UI that was being constructed. For cases where named outlets were being used it is likely that they should just be moved to components. For cases where you were escaping the existing DOM hierarchy to render a template somewhere else in the DOM, one should use the built-in [`{{in-element}}`](https://github.com/emberjs/rfcs/blob/master/text/0287-promote-in-element-to-public-api.md) helper or an addon like [ember-elsewhere](https://github.com/ef4/ember-elsewhere). Below are some example of how a migration would look. + +__Migrating Named Outlets__ + +Given: ```js Ember.Route.extend({ @@ -56,19 +60,190 @@ Luckily, we can express this entire concept with components. In the event you were using `model` to derive what to render, you can us the `{{component}}` helper to dynamically render a component. -## How We Teach This +__Migrating Hiearchy Escaping__ + +Given: + +```hbs +{{! app/templates/authenticated.hbs}} + + + +
+ {{outlet}} +
+``` + +```hbs +{{! app/templates/account.hbs }} +{{#link-to 'account'}} + {{this.name}} /> +{{/link-to}} +``` + +```js +// app/routes/authenticated.js +import Route from '@ember/route'; +import { inject as service } from '@ember/service'; + +export default Route.extend({ + // ... + user: service('user'), + renderTemplate() { + if (this.user.isLoggedIn) { + this.render('account', { + into: 'applcation', + outlet: 'account', + controller: 'account' + }); + } else { + this.transitionTo('login') + } + } +}); +``` + +One way this could be migrated is like the following: + +```hbs +{{! app/templates/authenticated.hbs}} + +<nav> + <h1>ACME Corp.</h1> + <section id= + + +
+ {{outlet}} +
+``` + +```hbs +{{! app/templates/authenticated/campaigns.hbs }} + +{{outlet}} + +{{#in-element this.accountPlaceholder}} + {{#link-to 'account'}} + {{this.account.name}} /> + {{/link-to}} +{{/in-element}} +``` + +```js +// app/routes/authenticated.js +import Route from '@ember/route'; +import { inject as service } from '@ember/service'; + +export default Route.extend({ + //... + user: service('user'), + beforeModel() { + if (!this.user.isLoggedIn) { + this.transitionTo('login') + } + } +}); +``` + +```js +// app/controller/authenticated/campaigns.js +import Route from '@ember/route'; +import Controller from '@ember/controller'; +import { inject as service } from '@ember/service'; +import { inject as controller } from '@ember/controller'; + +export default Controller.extend({ + //... + account: controller('account') + init() { + this._super(...arguments); + this.accountPlaceholder = document.getElementById('account-placeholder'); + } +}); +``` + +If you want to do this with components you could do the same thing as the following: + +```hbs +{{! app/templates/authenticated.hbs}} + +<nav> + <h1>ACME Corp.</h1> + <section id= + + +
+ {{outlet}} +
+``` + +```hbs +{{! app/templates/authenticated/campaigns.hbs }} +{{outlet}} + + +``` + +```hbs +{{! app/templates/components/user-account.hbs }} +{{#in-element this.accountPlaceholder}} + {{#link-to 'account'}} + {{this.account.name}} /> + {{/link-to}} +{{/in-element}} +``` + +```js +// app/routes/authenticated.js +import Route from '@ember/route'; +import { inject as service } from '@ember/service'; + +export default Route.extend({ + //... + user: service('user'), + beforeModel() { + if (!this.user.isLoggedIn) { + this.transitionTo('login') + } + } +}); +``` + +```js +// app/components/user-account.js +import Component from '@ember/route'; +import { inject as controller } from '@ember/controller'; + +export default Component.extend({ + // ... + account: controller('account'), + init() { + this._super(...arguments); + this.accountPlaceholder = document.getElementById('account-placeholder'); + } +}); +``` + +# How We Teach This This has not been a mainline API for quite some time now. The guides do not mention this functionality at all. It is likely that the majority of Ember applications do not use these APIs. ## Drawbacks -The drawback of this is we are saying that the `Route` and the route template of the same name are inherently coupled. In previous versions of Ember this didn't have to be so as long as you implemented `renderTemplate`. +The drawback of this is that it is churn for applications that are relying heavily of these imperative APIs to construct their UI. They will need to encapsulate and use the existing declarative APIs. ## Alternatives -No real alternatives. +No real alternatives as we want to move away from these style of imperative APIs in favor of declarative ones. ## Unresolved questions Optional, but suggested for first drafts. What parts of the design are still TBD? + From 43024f13c7460ecc6852fcf56d0b307b803bfe66 Mon Sep 17 00:00:00 2001 From: Chad Hietala <chadhietala@gmail.com> Date: Mon, 11 Feb 2019 09:24:32 -0500 Subject: [PATCH 4/5] Update 0418-deprecate-route-render-methods.md Add more process context. --- text/0418-deprecate-route-render-methods.md | 28 +++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/text/0418-deprecate-route-render-methods.md b/text/0418-deprecate-route-render-methods.md index 8c2d001463..bede58e93d 100644 --- a/text/0418-deprecate-route-render-methods.md +++ b/text/0418-deprecate-route-render-methods.md @@ -6,7 +6,22 @@ ## Summary -This RFC proposses the deprecation of [`Route#render`](https://emberjs.com/api/ember/3.6/classes/Route/methods/render?anchor=render), [`Route#renderTemplate`](https://emberjs.com/api/ember/3.6/classes/Route/methods/render?anchor=renderTemplate) and named `{{outlet}}` APIs. +This RFC proposses the deprecation of [`Route#render`](https://emberjs.com/api/ember/3.6/classes/Route/methods/render?anchor=render), [`Route#renderTemplate`](https://emberjs.com/api/ember/3.6/classes/Route/methods/render?anchor=renderTemplate) and named `{{outlet}}` APIs. The following deprecation message will be emitted upon usage of `render` or `renderTemplate`: + +``` +The usage of `renderTemplate` is deprecated. Please see the following deprecation guide to migrate. +``` +and + +``` +The usage of `render` is deprecated. Please see the following deprecation guide to migrate. +``` + +The following will be compile time deprecation for named outlets: + +``` +Please refatctor `{{outlet <NAME>}}` to a component <SOURCE_INFO>. +``` ## Motivation @@ -232,7 +247,16 @@ export default Component.extend({ # How We Teach This -This has not been a mainline API for quite some time now. The guides do not mention this functionality at all. It is likely that the majority of Ember applications do not use these APIs. +These APIs not been a mainline API for quite some time now. The guides briefly mention this functionality. In those cases we should mirgate the guides should link to the `{{in-element}}` documentation and the component documentation. The above Date: Mon, 11 Feb 2019 09:25:56 -0500 Subject: [PATCH 5/5] Update 0418-deprecate-route-render-methods.md SP --- text/0418-deprecate-route-render-methods.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0418-deprecate-route-render-methods.md b/text/0418-deprecate-route-render-methods.md index bede58e93d..f357ad4f3d 100644 --- a/text/0418-deprecate-route-render-methods.md +++ b/text/0418-deprecate-route-render-methods.md @@ -20,7 +20,7 @@ The usage of `render` is deprecated. Please see the following deprecation guide The following will be compile time deprecation for named outlets: ``` -Please refatctor `{{outlet }}` to a component . +Please refactor `{{outlet }}` to a component . ``` ## Motivation