From b002ae7a3ae3971c08fa3bc68819a3c91b1236de Mon Sep 17 00:00:00 2001 From: "L. Preston Sego III" Date: Thu, 14 Jun 2018 08:08:21 -0400 Subject: [PATCH 1/9] Create 0000-router-link-and-helpers.md --- text/0000-router-link-and-helpers.md | 56 ++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 text/0000-router-link-and-helpers.md diff --git a/text/0000-router-link-and-helpers.md b/text/0000-router-link-and-helpers.md new file mode 100644 index 0000000000..364791ba1a --- /dev/null +++ b/text/0000-router-link-and-helpers.md @@ -0,0 +1,56 @@ +- Start Date: (fill me in with today's date, YYYY-MM-DD) +- RFC PR: (leave this empty) +- Ember Issue: (leave this empty) + +# (RFC title goes here) + +## Summary + +> One paragraph explanation of the feature. + +## Motivation + +> Why are we doing this? What use cases does it support? What is the expected +outcome? + +## Detailed design + +> This is the bulk of the RFC. + +> Explain the design in enough detail for somebody +familiar with the framework to understand, and for somebody familiar with the +implementation to implement. This should get into specifics and corner-cases, +and include examples of how the feature is used. Any new terminology should be +defined here. + +## How we teach this + +> What names and terminology work best for these concepts and why? How is this +idea best presented? As a continuation of existing Ember patterns, or as a +wholly new one? + +> Would the acceptance of this proposal mean the Ember guides must be +re-organized or altered? Does it change how Ember is taught to new users +at any level? + +> How should this feature be introduced and taught to existing Ember +users? + +## Drawbacks + +> Why should we *not* do this? Please consider the impact on teaching Ember, +on the integration of this feature with other existing and planned features, +on the impact of the API churn on existing apps, etc. + +> There are tradeoffs to choosing any path, please attempt to identify them here. + +## Alternatives + +> What other designs have been considered? What is the impact of not doing this? + +> This section could also include prior art, that is, how other frameworks in the same domain have solved this problem. + +## Unresolved questions + +> Optional, but suggested for first drafts. What parts of the design are still +TBD? From 820d3e4ff0029bbb200eb647fb2759e9f1303712 Mon Sep 17 00:00:00 2001 From: "L. Preston Sego III" Date: Fri, 15 Jun 2018 09:19:09 -0400 Subject: [PATCH 2/9] Update 0000-router-link-and-helpers.md --- text/0000-router-link-and-helpers.md | 111 +++++++++++++++++++-------- 1 file changed, 81 insertions(+), 30 deletions(-) diff --git a/text/0000-router-link-and-helpers.md b/text/0000-router-link-and-helpers.md index 364791ba1a..bf41f95a87 100644 --- a/text/0000-router-link-and-helpers.md +++ b/text/0000-router-link-and-helpers.md @@ -1,56 +1,107 @@ -- Start Date: (fill me in with today's date, YYYY-MM-DD) -- RFC PR: (leave this empty) -- Ember Issue: (leave this empty) +- Start Date: 2018-06-15 +- RFC PR: +- Ember Issue: -# (RFC title goes here) +# Add a Link component and routing helpers ## Summary -> One paragraph explanation of the feature. +The purpose of this is to add a single component, `Link`, that wraps up some routing helpers for default usage of linking / routing. ## Motivation -> Why are we doing this? What use cases does it support? What is the expected -outcome? +Currently, on ember#canary, the Angle Bracket Invocation feature doesn't support positional arguments. For clarity, and with some inspiration from react-router, It may be beneficial for Ember to include a `Link` component, similar to the existing `LinkTo` (`link-to`), but with only named arguments. This will help with clarity of intent, and also allow for easier transitioning from other communities who already have named-argument links. ## Detailed design -> This is the bulk of the RFC. - -> Explain the design in enough detail for somebody -familiar with the framework to understand, and for somebody familiar with the -implementation to implement. This should get into specifics and corner-cases, -and include examples of how the feature is used. Any new terminology should be -defined here. +Helpers to be implemented: + - `transition` + this is a helper that would tie into the router to be able to achive the same functionality as the simple usage of `LinkTo` + + example: + + ``` + + + ``` - - - `replace-with` - this is same as transition, but replaces the current URL and current history entry. This may be an argument to transition instead. e.g.: `(transition ... replace=true)` - + + + - `is-route-active` this returns a boolean representing whether or not the current route matches the passed argument. - + example: - - ``` - ``` -Inspiration for helpers implementation could come from https://github.com/BBVAEngineering/ember-route-helpers +#### Phase 2 + +*Add `Link` Component* - Components to be implemented: - - `Link` - `Link` could just be tagless component with the following template: + ```hbs {{!-- components/link/template.hbs --}} - + -{{yield}} + {{yield}} - ``` +``` Usage: ```hbs -Edit Post +Edit Post ``` +where `@models` can be a `hash`, `array`, or just a single object or id. + **Deprecation** `LinkTo` aka `link-to` @@ -93,7 +137,7 @@ Without positional params, the alternative may need to use the `array` helper fo There are two alternatives: -1. Do nothing: +1. Do nothing: - people will find that the `LinkTo` usage with angle bracket invocation to be somewhat awkward, maybe unintuitive. 2. Only implement the routing helpers - people could define their own linking components however they desire @@ -105,3 +149,9 @@ There are two alternatives: - For routes with multiple segment parameters, it may become hard to keep track of things. e.g.: `(array 'posts.edit.comments.reply' post comment.id)` how do I know where the parameters are going to go without looking at the router.js file? (though, this is an existing question) - Would it make sense to somehow have a way to statically confirm that the route path is valid? right now, it looks like a string -- how would I know if I typed it wrong? + +## Inspiration / Code taken from +- https://github.com/alexspeller/ember-cli-active-link-wrapper +- https://github.com/BBVAEngineering/ember-route-helpers +- https://github.com/peec/ember-transition-helper +- https://github.com/rwjblue/ember-router-helpers From db59e8baa3b094f0d50b6d0255a027aeedc9ff81 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli Date: Sat, 11 Aug 2018 13:45:30 -0400 Subject: [PATCH 6/9] formatting, update questions --- text/0000-router-link-and-helpers.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/text/0000-router-link-and-helpers.md b/text/0000-router-link-and-helpers.md index 74e8681b04..f75ae2fcaa 100644 --- a/text/0000-router-link-and-helpers.md +++ b/text/0000-router-link-and-helpers.md @@ -114,6 +114,8 @@ Usage: where `@models` can be a `hash`, `array`, or just a single object or id. + + **Deprecation** `LinkTo` aka `link-to` The goal of `Link` and the route helpers is to provide a flexible way of routing from the template while providing a sample component with sensible defaults. This would achieve the exact same functionality as `LinkTo`, so `LinkTo` would no longer be needed and could eventually be removed. @@ -144,9 +146,10 @@ There are two alternatives: ## Unresolved questions -- Is there a way for making `(array 'posts.edit' post)` more ergonomic? _having_ to use the array helper _seems_ like it shouldn't be a thing. Maybe if the `transition-to` helper took named arguments without `hash`? transition can be implemented to support this:`(transition to='posts.edit' postId=post.id)`.. but for `Link`, I don't know how the route arguments would get passed to `transition`. - -- For routes with multiple segment parameters, it may become hard to keep track of things. e.g.: `(array 'posts.edit.comments.reply' post comment.id)` how do I know where the parameters are going to go without looking at the router.js file? (though, this is an existing question) +- Should we offer additional click APIs on `Link`? such as: + - onclick / onclick + - beforeTransition + - etc? - Would it make sense to somehow have a way to statically confirm that the route path is valid? right now, it looks like a string -- how would I know if I typed it wrong? From 20f55701014fd621198ca1f09f7d4b956f5b5f46 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli Date: Sat, 11 Aug 2018 13:46:07 -0400 Subject: [PATCH 7/9] formatting --- text/0000-router-link-and-helpers.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/text/0000-router-link-and-helpers.md b/text/0000-router-link-and-helpers.md index f75ae2fcaa..112cc1bd1c 100644 --- a/text/0000-router-link-and-helpers.md +++ b/text/0000-router-link-and-helpers.md @@ -33,19 +33,20 @@ Currently, on ember#canary, the Angle Bracket Invocation feature doesn't support `@routeName` and `@models` will allow us to smoothly transition away from `{{link-to}}` into the `` invocation-style. - example: + - example: - ```hbs - {{!-- before --}} - {{#link-to 'posts.edit' post.id}} - Edit - {{/link-to}} + ```hbs + {{!-- before --}} + {{#link-to 'posts.edit' post.id}} + Edit + {{/link-to}} + + {{!-- After --}} + + Edit + + ``` - {{!-- After --}} - - Edit - - ``` The `` invocation with named arguments is more verbose, but trade-off here is the added clarity of what argument is used for what purpose -- especially with respect to the models / model ids. From f7da2c2ed23384fa8c0ef9d99cf1eb2d536f5684 Mon Sep 17 00:00:00 2001 From: "L. Preston Sego III" Date: Thu, 30 Aug 2018 07:06:23 -0400 Subject: [PATCH 8/9] Update 0000-router-link-and-helpers.md --- text/0000-router-link-and-helpers.md | 67 +++++++--------------------- 1 file changed, 15 insertions(+), 52 deletions(-) diff --git a/text/0000-router-link-and-helpers.md b/text/0000-router-link-and-helpers.md index 112cc1bd1c..1b04c4fd74 100644 --- a/text/0000-router-link-and-helpers.md +++ b/text/0000-router-link-and-helpers.md @@ -10,50 +10,26 @@ The purpose of this is to add a single component, `Link`, that wraps up some rou ## Motivation -Currently, on ember#canary, the Angle Bracket Invocation feature doesn't support positional arguments. For clarity, and with some inspiration from react-router, It may be beneficial for Ember to include a `Link` component, similar to the existing `LinkTo` (`link-to`), but with only named arguments. This will help with clarity of intent, and also allow for easier transitioning from other communities who already have named-argument links. +Positional arguments are not planned for use with Angle Bracket invocations. For clarity, and with some inspiration from react-router, It may be beneficial for Ember to include a `Link` component, similar to the existing `link-to`, but with only named arguments. This will help with clarity of intent, and also allow for easier transitioning from other communities who already have named-argument links. ## Detailed design -#### tl;dr: - *Phase 1* -- add named arguments to `LinkTo`: `@routeName` and `@models` - add built-in helpers for custom link-like behavior +- add `Link` component with `@to` named argument -- all other named arguments will be the params *Phase 2* -- add `Link` component with `@to` named argument -- all other named arguments will be the params - deprecate `LinkTo` *Phase 3* - remove `LinkTo` and the corresponding deprecation - -#### Phase 1 -*Add Named Arguments to `LinkTo`* - - `@routeName` and `@models` will allow us to smoothly transition away from `{{link-to}}` into the `` invocation-style. - - - example: - - ```hbs - {{!-- before --}} - {{#link-to 'posts.edit' post.id}} - Edit - {{/link-to}} - - {{!-- After --}} - - Edit - - ``` - - - The `` invocation with named arguments is more verbose, but trade-off here is the added clarity of what argument is used for what purpose -- especially with respect to the models / model ids. +### Details *Helpers to be implemented* - `transition` - this is a helper that would tie into the router to be able to achieve the same functionality as the navigational usage of `LinkTo` + this is a helper that would tie into the router to be able to achieve the same functionality as the navigational usage of `link-to` examples: @@ -69,7 +45,7 @@ Currently, on ember#canary, the Angle Bracket Invocation feature doesn't support - - `is-route-active` + - `is-active` this returns a boolean representing whether or not the current route matches the passed argument. example: @@ -77,7 +53,7 @@ Currently, on ember#canary, the Angle Bracket Invocation feature doesn't support ```hbs ``` -#### Phase 2 *Add `Link` Component* @@ -114,46 +89,34 @@ Usage: where `@models` can be a `hash`, `array`, or just a single object or id. +Starting with @rwjblue's [ember-router-helpers](https://github.com/rwjblue/ember-router-helpers) as a base, `is-active` is already implemented, along with `route-params`, `transition-to`, and `url-for`. +A [PR](https://github.com/rwjblue/ember-router-helpers/pull/46) has been started that aims to implement the `transition` helper (or just rename `transition-to`), as well as implement the `Link` component. -**Deprecation** `LinkTo` aka `link-to` -The goal of `Link` and the route helpers is to provide a flexible way of routing from the template while providing a sample component with sensible defaults. This would achieve the exact same functionality as `LinkTo`, so `LinkTo` would no longer be needed and could eventually be removed. +**Deprecation** `link-to` aka `link-to` -It's possible we could write a codemod to auto-convert everyone's non-angle-bracket invocation of `{{#link-to ...` to the new angle bracket component: `Link` +The goal of `Link` and the route helpers is to provide a flexible way of routing from the template while providing a sample component with sensible defaults. This would achieve the exact same functionality as `link-to`, so `link-to` would no longer be needed and could eventually be removed. ## How we teach this -We'll want to make it very clear that the traditional `LinkTo` technique of linking will still be available, but will eventually be deprecated. +We'll want to make it very clear that the traditional `link-to` technique of linking will still be available, but will eventually be deprecated. -The documentation and guides would need to be incrementally upgraded to inform people about the new linking strategy -- but becaus the old way would still work, having some docs say `LinkTo` instead of `Link` wouldn't be the worst thing. +The documentation and guides would need to be incrementally upgraded to inform people about the new linking strategy -- but because the old way would still work, having some docs say `link-to` instead of `Link` wouldn't be the worst thing. ## Drawbacks The biggest drawback is that all routing documentation would be out of date, and there is a lot of routing documentation and blog posts throughout the web. -Without positional params, the alternative may need to use the `array` helper for the `@to` argument... which could almost make people wonder why `LinkTo` didn't get a named argument for the route / route params. With the `Link` component, the arguments would read more ergonomically -- ` Date: Thu, 30 Aug 2018 18:55:39 -0400 Subject: [PATCH 9/9] Update 0000-router-link-and-helpers.md --- text/0000-router-link-and-helpers.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/text/0000-router-link-and-helpers.md b/text/0000-router-link-and-helpers.md index 1b04c4fd74..202841c7fe 100644 --- a/text/0000-router-link-and-helpers.md +++ b/text/0000-router-link-and-helpers.md @@ -45,7 +45,7 @@ Positional arguments are not planned for use with Angle Bracket invocations. For - - `is-active` + - `is-route-active` this returns a boolean representing whether or not the current route matches the passed argument. example: @@ -53,7 +53,7 @@ Positional arguments are not planned for use with Angle Bracket invocations. For ```hbs ``` @@ -74,7 +74,8 @@ Positional arguments are not planned for use with Angle Bracket invocations. For ```hbs {{!-- components/link/template.hbs --}} {{yield}} @@ -89,13 +90,13 @@ Usage: where `@models` can be a `hash`, `array`, or just a single object or id. -Starting with @rwjblue's [ember-router-helpers](https://github.com/rwjblue/ember-router-helpers) as a base, `is-active` is already implemented, along with `route-params`, `transition-to`, and `url-for`. +Starting with @rwjblue's [ember-router-helpers](https://github.com/rwjblue/ember-router-helpers) as a base, `is-route-active` is already implemented (as `is-active`, so this would need to be renamed), along with `route-params`, `transition-to`, and `url-for`. -A [PR](https://github.com/rwjblue/ember-router-helpers/pull/46) has been started that aims to implement the `transition` helper (or just rename `transition-to`), as well as implement the `Link` component. +A [PR](https://github.com/rwjblue/ember-router-helpers/pull/46) has been started that upgrades `ember-router-helpers` and adds tests in preparation for implementing the helper renames and `Link` component. -**Deprecation** `link-to` aka `link-to` +**Deprecation** `link-to` The goal of `Link` and the route helpers is to provide a flexible way of routing from the template while providing a sample component with sensible defaults. This would achieve the exact same functionality as `link-to`, so `link-to` would no longer be needed and could eventually be removed.