| stage | start-date | release-date | release-versions | teams | prs | project-link | meta | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
recommended |
2017-12-10 00:00:00 UTC |
2018-04-10 00:00:00 UTC |
|
|
|
|
Introduce {{@foo}} in as a dedicated syntax for a component's template to
refer to named arguments passed in by the caller.
For example, given the invocation {{hello-world name="Godfrey"}} and this
component template in app/templates/components/hello-world.hbs:
Ember will render "Hello, Godfrey".
Currently, the way to access named arguments passed in from the caller is to
reference {{name}} in the template. This works because when Ember creates
the component instance, it automatically assigns
all named arguments as properties on the component instance.
The first problem with this approach is that the {{name}} syntax is highly
ambigious, as it could be referring to a local variable (block param), a
helper or a named argument from the caller (which actually works by accessing
auto-reflected {{this.name}}) or a property on the component class (such as
a computed property).
This can often lead to confusion for readers of the template. Upon encountering
{{foo}} in a component's template, the reader has to check all of
these places: first you need to scan the surrounding lines for block
params with that name; next you check in the helpers folder to see if there
is a helper with that name (it could also be coming from an addon!); then you
check if it is an argument provided by the caller; finally, you check the
component's JavaScript class to look for a (computed) property. If you still
did not find it, maybe it is a named arguments that is passed only sometimes,
or perhaps it is just a leftover reference from a previous refactor?
Providing a dedicated syntax for referring to named arguments will resolve the
ambiguity and greatly improve clarity, especially in big projects with a lot
of files (and uses a lot of addons). (The existing {{this.name}} syntax can
already be used to disambiguate component properties from helpers.)
As an aside, the ambiguity that causes confusion for human readers is also a
problem for the compiler. While it is not the main goal of this proposal,
resolving this ambiguity also helps the rendering system. Currently, the
"runtime" template compiler has to perform a helper lookup for every {{name}}
in each template. It will be able to skip this resolution process and perform
other optimizations (such as reusing the internal reference
object and caches) with this addition.
Another problem with the current approach of automatically "reflecting" named arguments on the instance is that they can unexpectedly overwrite other properties defined on the component's class. It also defeats performance optimizations in JavaScript engines as this approach creates many different polymorphic "shapes" for instances that otherwise belong to the same component class.
While this proposal does not directly solve this problem (we are not proposing
that we deprecate or remove the "auto-reflection" on Ember.Component), it
paves the way for a future world where components can work without them.
Notably, the current iteration of the Glimmer Components have adopted this design for over a year now and the experience has been very positive. This would be one of the first pieces (admittedly, only a tiny piece) of the Glimmer.js experiment to make its way into Ember. We think this feature is small, self-contained but useful enough to be the ideal candidate to kick off this process.
This feature was baked into the Glimmer VM very early on. In fact, the only thing that is stopping them from working in Ember is an AST transform that specifically disallows them. Therefore, "implementing" this feature is just a matter of deleting that file.
Additionally, the legacy {{attrs.foo}} syntax (which more or less tries to
accomplish the same thing) has actually been implemented using {{@foo}}
under-the-hood since Ember 2.10.
We will reserve {{@args}}, {{@arguments}} and anything that does not
start with a lowercase letter (such as @Foo, @0, @! etc) in the first
version. This is purely speculative and the goal is to carve out some space
for future features. If we don't end up needing them, we can always relax
the restrictions down the road.
{{@foo}} is the way to access the named arguments passed from the caller.
Since the {{foo}} syntax still works on Ember.Component (which is the
only kind of components available today) via the auto-reflection mechanism,
we are not really in a rush to migrate the community (and the guides, etc)
to using the new syntax. In the meantime, this could be viewed as a tool to
improve clarity in templates, similar to how the optional "explicit this"
syntax ({{this.foo}}).
While we think writing {{@foo}} would be a best practice for new code
going forward, the community can migrate at its own pace one component at a
time.
We can also encourage the community to supplement this effort by wiring linting tools and code mods.
This introduces a new piece of syntax that one would need to learn in order to understand Ember templates.
This mostly affects "casual" readers (as this should be very easy for an Ember developer to learn, understand and remember after encounting/learning it for the first time). However, since these casual readers are also among those who are most acutely affected by the ambiguity, we believe this is still a net improvement over the status-quo.
We have {{attrs.foo}} today. In React, there is this.props.foo.
Given how common this is, we think it deserves its own dedicated, succinct syntax. The other alternatives that involve reflecting them on the component instances also would not allow for the internal optimizations in the Glimmer VM.