Skip to content

Commit 7738818

Browse files
ef4ef4
committed
Template Tag In Routes
1 parent 91417a5 commit 7738818

File tree

1 file changed

+184
-0
lines changed

1 file changed

+184
-0
lines changed

‎text/1046-template-tag-in-routes.md

+184
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
stage: accepted
3+
start-date: 2024-10-04T00:00:00.000Z
4+
release-date: # In format YYYY-MM-DDT00:00:00.000Z
5+
release-versions:
6+
teams: # delete teams that aren't relevant
7+
- framework
8+
- learning
9+
- typescript
10+
prs:
11+
accepted: 1046
12+
project-link:
13+
suite:
14+
---
15+
16+
<!---
17+
Directions for above:
18+
19+
stage: Leave as is
20+
start-date: Fill in with today's date, 2032-12-01T00:00:00.000Z
21+
release-date: Leave as is
22+
release-versions: Leave as is
23+
teams: Include only the [team(s)](README.md#relevant-teams) for which this RFC applies
24+
prs:
25+
accepted: Fill this in with the URL for the Proposal RFC PR
26+
project-link: Leave as is
27+
suite: Leave as is
28+
-->
29+
30+
# Use Template Tag in Routes
31+
32+
## Summary
33+
34+
Allow `app/templates/*.hbs` to convert to `app/temlates/*.gjs`.
35+
36+
## Motivation
37+
38+
We are rapidly approaching the point where Template Tag is the recommended way to author components. This means using `.gjs` (or `.gts`) files that combine your template and Javascript into one file. But you cannot currently use Template Tag to author the top-level templates invokes by the router (`app/templates/*.hbs`).
39+
40+
This inconsistency is especially apparent when working on teaching materials for new users. Making people learn both `.hbs` with global component resolution and `.gjs` with strict template resolution before they can even make their first component is unreasonable.
41+
42+
This RFC proposes allowing consistent use of `.gjs` everywhere. It doesn't remove any support for `.hbs`, but recommends that the guides default to all `.gjs`.
43+
44+
## Detailed design
45+
46+
The [implementation is small and already done](https://github.com/emberjs/ember.js/pull/20768).
47+
48+
### Illustration By Example
49+
50+
If you currently have this:
51+
52+
```hbs
53+
{{! app/templates/example.hbs }}
54+
<article>
55+
<MainContent @model={{@model}} @editorMode={{this.editorMode}} />
56+
</article>
57+
```
58+
59+
You can convert it to this:
60+
61+
```gjs
62+
// app/templates/example.gjs
63+
import MainContent from 'my-app/components/main-content';
64+
<template>
65+
<article>
66+
<MainContent @model={{@model}} @editorModel={{@controller.editorMode}} />
67+
</article>
68+
</template>
69+
```
70+
71+
Key differences:
72+
73+
- this is [strict handlebars](https://github.com/emberjs/rfcs/blob/master/text/0496-handlebars-strict-mode.md), so components are imported explicitly
74+
- the controller is no longer `this`, it is `@controller`.
75+
76+
Many things that you might have been forced to put on a controller can now be done directly. For example, if your controller has a `doSomething` event handler:
77+
78+
```hbs
79+
{{! app/templates/example.hbs }}
80+
<div {{on "click" this.doSomething }}></div>
81+
```
82+
83+
You now have options to implement it in-place in the same file. If it's stateless it can just be a function:
84+
85+
```gjs
86+
// app/templates/example.gjs
87+
88+
// This import will be unnecessary after https://github.com/emberjs/rfcs/pull/1033
89+
import { on } from '@ember/modifier';
90+
91+
function doSomething() {
92+
alert("It worked");
93+
}
94+
95+
<template>
96+
<div {{on "click" this.doSomething }}></div>
97+
</template>
98+
```
99+
100+
If it's stateful, you can upgrade from a template-only component to a Glimmer component:
101+
102+
```gjs
103+
// app/templates/example.gjs
104+
import { on } from '@ember/modifier';
105+
import Component from '@glimmer/component';
106+
import { tracked } from '@glimmer/tracking';
107+
108+
export default class extends Component {
109+
@tracked activated = false;
110+
111+
doSomething = () => {
112+
this.activated = !this.activated;
113+
}
114+
115+
<template>
116+
<div {{on "click" this.doSomething }}></div>
117+
{{#if this.activated}}
118+
It's activated!
119+
{{/if}}
120+
</template>
121+
}
122+
```
123+
124+
### Implementation
125+
126+
When Ember resolves a route template:
127+
128+
1. Check whether the resulting value has a component manager.
129+
- If no, do exactly what happens today.
130+
- If yes, continue to step 2.
131+
2. Synthesize a route template that invokes your component with these arguments:
132+
- @model: which means exactly the same as always.
133+
- @controller: makes the controller available.
134+
135+
Keen observers will notice that this says nothing about only supporting gjs files. Any component is eligible, no matter how it's authored or what Component Manager it uses. This is by design, because there's no reason for the router to violate the component abstraction and care about how that component was implemented.
136+
137+
However, in our learning materials we should present this as a feature designed for GJS files. Using it with components authored in .hbs would be needlessly confusing, because automatic template co-location **does not work in app/templates**, because it would collide with traditional route templates.
138+
139+
### ember-route-template addon
140+
141+
This RFC replaces the [ember-route-template](https://github.com/discourse/ember-route-template) addon. If you're already using it, it would continue to work without breaking, but you can simply delete all the calls to its `RouteTemplate` function and remove it. The popularity of that addon among teams who are already adopting Template Tag is an argument in favor of this RFC.
142+
143+
### Codemod
144+
145+
Because Embroider already generates imports for components, helpers, and modifiers in non-strict templates, there is [ongoing work](https://github.com/embroider-build/embroider/pull/2134) to offer Embroider's existing functionality as a Template Tag codemod.
146+
147+
For route templates, the only extra feature required would be replacing `this` with `@controller`.
148+
149+
### TypeScript
150+
151+
No new typescript-specific features are required. If you're authoring route templates in GTS, Glint should treat them just like any other component. You will need to manually declare the signature for `@model` and `@controller`, but that is the same as now.
152+
153+
## How we teach this
154+
155+
This RFC was directly inspired by a first attempt at updating the Guides for Template Tag. It became immediately apparent that we can write *much* clearer guides if we can teach all GJS, instead of a mix of GJS and HBS.
156+
157+
Starting at https://guides.emberjs.com/release/components/ when the first `application.hbs` file is introduced, we would use `.gjs` instead. In those opening examples that are empahsizing HTML, the only change to the content would be wrapping `<template></template>` around the HTML.
158+
159+
Progressing to https://guides.emberjs.com/release/components/introducing-components/, learners extract their first component. It now becomes possible to do that within the same file. This allows teaching fewer things in a single step. First, people can learn what a component is. Second, it can be refactored into a separate file. We can avoid teaching anything about "pascal case" and naming rules, because everything just follows javascript naming rules.
160+
161+
When starting to teach routing in https://guides.emberjs.com/release/routing/defining-your-routes/, the file extensions change and `<template></template>` wrappers are added, but nothing else on that page necessarily changes.
162+
163+
In https://guides.emberjs.com/release/routing/query-params/, it's appropriate to first introduce the `@controller` argument.
164+
165+
In https://guides.emberjs.com/release/routing/controllers/, the list of reasons to use a controller gets shortened to only queryParams, since now you can manage state directly in your route's component.
166+
167+
168+
## Drawbacks
169+
170+
There is appetite for a more ambitious RFC that changes more things about routing. Eliminating controllers, making routes play nice with the newer `@ember/destroyable` system, allowing parallel model hooks, etc, are all good goals. There is a risk that if we do those things soon, this would be seen as two steps of churn instead of one.
171+
172+
I think we can mitigate that risk because
173+
- we won't deprecate `.hbs` routes yet, so no churn is forced immediately.
174+
- we can ship the Template Tag codemod so that even big apps can adopt at low cost
175+
- it's extremely unlikely that a future routing design would use anything other than `.gjs` to define route entrypoints. By converting now, you are already moving in the right direction by eliminating all the non-strict behaviors.
176+
177+
178+
## Alternatives
179+
180+
The main alternative here is to do a bigger change to the routing system. A "Route Manager" RFC would allow the creation of new Route implementations that could have their own opinions about how to route to GJS files. This RFC does not preclude that other work from also happening.
181+
182+
The main benefit of this RFC is that the [implementation is small and already done](https://github.com/emberjs/ember.js/pull/20768) so we could have it immediately.
183+
184+

0 commit comments

Comments
 (0)