diff --git a/text/0000-router-link-and-helpers.md b/text/0000-router-link-and-helpers.md new file mode 100644 index 0000000000..c5d0d1e462 --- /dev/null +++ b/text/0000-router-link-and-helpers.md @@ -0,0 +1,124 @@ +- Start Date: 2018-06-15 +- RFC PR: +- Ember Issue: + +# Add a Link component and routing helpers + +## Summary + +The purpose of this is to add a single component, `Link`, that wraps up some routing helpers for default usage of linking / routing. + +## Motivation + +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 + +*Phase 1* +- 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* +- deprecate `LinkTo` + +*Phase 3* +- remove `LinkTo` and the corresponding deprecation + +### 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 `link-to` + + examples: + + ```hbs + + + + ``` + + + + - `is-route-active` + this returns a boolean representing whether or not the current route matches the passed argument. + + example: + + ```hbs + + ``` + + +*Add `Link` Component* + +`Link` could just be tagless component with the following template: + +```hbs +{{!-- components/link/template.hbs --}} + + + {{yield}} + + +``` + +Usage: +```hbs +Edit Post +``` + +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-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 upgrades `ember-router-helpers` and adds tests in preparation for implementing the helper renames and `Link` component. + + + +**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. + +## How we teach this + +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 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 would feel awkward enough to make people wonder why `link-to` (as `LinkTo`) didn't get a named argument for the route / route params. With the `Link` component, the arguments would read more ergonomically -- `