Skip to content

Commit 94291b2

Browse files
committed
Describe changes to guides for components w/behavior
1 parent 0fdfc1d commit 94291b2

File tree

1 file changed

+13
-5
lines changed

1 file changed

+13
-5
lines changed

text/0000-template-imports.md

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -496,15 +496,23 @@ Once this is implemented and tooling is sufficiently stable, we will update the
496496
- Update the introductory examples, which start with pure HTML, to add a wrapping `<template>` tag, and update the prose to describe that `<template>` marks this as Ember/Glimmers special superset of HTML. Note that all you need to do to have a working Ember component is to wrap your HTML in `<template>`.
497497

498498
- Introducing components will see the most changes, unsurprisingly:
499-
- Note that we have already seen components in practice, because the templates we used with our routes were also components.
499+
- Note that we have already seen components in practice, because the templates we used with our routes were also components.
500500

501-
- While we *conventionally* use `<CapitalizedComponents />` (and historically *had* to because that was the decision for how the resolver would work), thats no longer a hard constraint. If someone does `const foo = <template>...</template>`, they will be able to invoke that as `<foo />` elsewhere. The notes in this section as well as about `LinkTo` will need to be updated to describe this as a helpful convention.
501+
- While we *conventionally* use `<CapitalizedComponents />` (and historically *had* to because that was the decision for how the resolver would work), thats no longer a hard constraint. If someone does `const foo = <template>...</template>`, they will be able to invoke that as `<foo />` elsewhere. The notes in this section as well as about `LinkTo` will need to be updated to describe this as a helpful convention.
502502

503-
- After introducing `<Jumbo />` with updated use of a wrapping `<template>`, discuss *importing it* into the route (component) template which uses it. This is a good place to describe how `.gjs` can use JS features, and hint that well see more of this later; it is also a good opportunity to note that we *could* have defined `<Jumbo />` locally, but that we moved it to a separate file because were sharing it across multiple different components.
503+
- After introducing `<Jumbo />` with updated use of a wrapping `<template>`, discuss *importing it* into the route (component) template which uses it. This is a good place to describe how `.gjs` can use JS features, and hint that well see more of this later; it is also a good opportunity to note that we *could* have defined `<Jumbo />` locally, but that we moved it to a separate file because were sharing it across multiple different components.
504504

505-
- Our discussion of the testing will need to be updated to include importing the components under test, and to use `<template>` rather than `hbs` strings for the `render` calls.[^testing-rfc]
505+
- Our discussion of the testing will need to be updated to include importing the components under test, and to use `<template>` rather than `hbs` strings for the `render` calls.[^testing-rfc]
506506

507-
- We can simply *remove* the discussion of namespaced components, in favor of simply describing the use of normal JS imports to accomplish the same goal. However, here we can also note that JavaScript modules are a great way to organize groups of related components, and show how we might use namespace-style imports (`import * as Rental from '';` and then `<Rental.Image />` within a `<template>`) for this kind of organization.[^namespace-deprecation]
507+
- We can simply *remove* the discussion of namespaced components, in favor of simply describing the use of normal JS imports to accomplish the same goal. However, here we can also note that JavaScript modules are a great way to organize groups of related components, and show how we might use namespace-style imports (`import * as Rental from '';` and then `<Rental.Image />` within a `<template>`) for this kind of organization.[^namespace-deprecation]
508+
509+
- The discussion of adding behavior to components will need to be updated as follows:
510+
511+
1. Show that when we generate a class for an existing component, it adds the `Component` import, creates a wrapping class, and moves the template into the body of that class. Here, teach the mental model that a `<template>` which is part of a class body has access to the instance properties on the backing class.
512+
513+
2. When discussing use of values from `ENV`, instead of providing a getter on a backing class, start by creating a `TOKEN` constant in module scope, and show that it is available to access in the template. In the following section, which shows args being used in the template, simply use that `TOKEN` value in the template directly, `access_token={{TOKEN}}`.
514+
515+
3. When refactoring to use a getter for `src`, use the value as `${TOKEN}`. Note explicitly how there is a symmetry between JS and templates: you can use whichever approach is clearer for a given context.
508516
509517
<!-- TODO: the rest of the pedagogy updates -->
510518

0 commit comments

Comments
 (0)