Skip to content

Commit 3b52b8e

Browse files
chadhietalachadhietala
committed
Modifiers
1 parent e2d845b commit 3b52b8e

File tree

1 file changed

+242
-0
lines changed

1 file changed

+242
-0
lines changed

‎text/0000-modifiers.md

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
- Start Date: (fill me in with today's date, YYYY-MM-DD)
2+
- RFC PR: (leave this empty)
3+
- Ember Issue: (leave this empty)
4+
5+
Element Modifiers
6+
7+
## Summary
8+
9+
This RFC introduces the concept of user defined element modfiers. Unlike a component, there is no template/layout for an element modifier. Unlike a helper, an element modifier does not return a value.
10+
11+
Below is an example of the element modifier syntax:
12+
13+
```hbs
14+
<button {{add-event-listener 'click' (action 'save')}}>Save</button>
15+
```
16+
17+
This RFC supercedes the [original element modifiers RFC](https://github.com/emberjs/rfcs/pull/112) and is intended to replace the [`this.bounds` RFC](https://github.com/emberjs/rfcs/pull/351).
18+
19+
## Motivation
20+
21+
Classic component instances have a `this.element` property which provides you a single DOM node as defined by `tagName`. It's children of this node will be the DOM representation of what you wrote in your template, this is typically referred to as `innerHTML` semantics. These semantics allow for components to encapsulate some 3rd party JavaScript library or do some fine grain DOM manipulation.
22+
23+
Glimmer components have `outerHTML` semantics, meaning what you see in the template is what you get in the DOM, there is no `tagName` that wraps the template. While this drastically simplifies API for creating new components it makes reliable access to the a component's DOM structure very difficult to do. As [pointed out](https://github.com/emberjs/rfcs/pull/351#issuecomment-412123046) in the [Bounds RFC](https://github.com/emberjs/rfcs/pull/351) the stability of the nodes in the `Bounds` object creates way too many footguns. So a formalized way for accessing DOM in the Glimmer component world is still needed.
24+
25+
Element modifiers allow for stable access of the DOM node they are installed on. This allows for programatic assess to DOM in Glimmer templates and also offers a more targeted construct for cases where classic components were being used. The introduction of this API will likely result in the proliferation of one or several popular addons for managing element event listeners, style and animation.
26+
27+
## Detailed design
28+
29+
### Invocation
30+
31+
An element modifier is invoked in "element space". This is the space between `<` and `>` opening an HTML tag. For example:
32+
33+
```hbs
34+
<button {{flummux}}></button>
35+
<span {{whipperwill 'carrot'}}><i>Some DOM</i></span>
36+
<b {{crum bing='whoop'}} zip="bango">Hm...</b>
37+
```
38+
39+
Element modifiers may be invoked with params or hash arguments.
40+
41+
### Definition and lookup
42+
43+
A basic element modifier is defined with the type of `element-modifier`. For example these paths would be global element modifiers in an application:
44+
45+
```
46+
Classic paths:
47+
48+
app/element-modifiers/flummux.js
49+
app/element-modifiers/whipperwill.js
50+
51+
MU paths:
52+
53+
src/ui/components/flummux/element-modifier.js
54+
src/ui/routes/posts/-components/whipperwill/element-modifier.js
55+
```
56+
57+
Element modifiers, like component and helpers, are eligible for local lookup. For example:
58+
59+
```
60+
MU paths:
61+
62+
src/ui/routes/posts/-components/post-editor/flummux/element-modifier.js
63+
```
64+
65+
The element modifier class is a default export from these files. For example:
66+
67+
```js
68+
import { Modifier } from '@ember/modifiers';
69+
70+
export default class extends Modifier {}
71+
```
72+
73+
### Lifecycle Hooks
74+
75+
During rendering and teardown of a target element, any attached element modifiers will execute a series of hooks. These hooks are:
76+
77+
* `didInsertElement`
78+
* `didUpdate`
79+
* `willDestroyElement`
80+
81+
It is important to note that in server-side rendering environments none of the lifecycle events are called.
82+
83+
#### `didInsertElement` semantics
84+
85+
`didInsertElement` is called when the element is in the DOM and it's children are attached. The element is available on `this.element` of the modifier instance. Unlike classic components, the `didInsertElement` hook receives the positional and named params as arguments in the same way helpers do. This hook is only called once.
86+
87+
This hook has the following timing semantics:
88+
89+
**Always**
90+
- called **after** any children modifiers `didInsertElement` hook are called
91+
- called **after** DOM insertion
92+
93+
**May or May Not**
94+
- be called in the same tick as DOM insertion
95+
- have the the parent's children fully initialized in DOM
96+
97+
Below is an example of how this hook could be used:
98+
99+
```js
100+
import { Modifier } from '@ember/modifiers';
101+
102+
export default class extends Modifier {
103+
this.listnerOptions = undefined;
104+
didInsertElement([ eventType, callback ], eventOptions) {
105+
this.listenerOptions = [
106+
eventType,
107+
callBack,
108+
eventOptions
109+
];
110+
this.element.addEventListener(eventType, callback, eventOptions);
111+
}
112+
}
113+
```
114+
115+
#### `didUpdate` semantics
116+
117+
`didUpdate` is called whenever any of the parameters used by the modifier are updated. `didUpdate` has the same signature as `didInsertElement`.
118+
119+
This hook has the following timing semantics:
120+
121+
**Always**
122+
- called **after** the arguments to the modifier have changed
123+
124+
**Never**
125+
- called if the arguments to the modifier are constants
126+
127+
Below is an example of how this hook could be used:
128+
129+
```js
130+
import { Modifier } from '@ember/modifiers';
131+
132+
export default class extends Modifier {
133+
this.listnerOptions = undefined;
134+
didInsertElement([ eventType, callback ], eventOptions) {
135+
this.listenerOptions = [
136+
eventType,
137+
callBack,
138+
eventOptions
139+
];
140+
this.element.addEventListener(eventType, callback, eventOptions);
141+
},
142+
143+
didUpdate([ eventType, callback ], eventOptions) {
144+
this.element.removeEventListener(...this.listenerOptions);
145+
this.element.addEventListener(eventType, callback, eventOptions);
146+
this.listnerOptions = [eventType, callback, eventOptions];
147+
}
148+
}
149+
```
150+
151+
#### `willDestroyElement` semantics
152+
153+
`willDestroyElement` is called during the destruction of a template. It receives no arguments.
154+
155+
Below is an example of how this hook could be used:
156+
157+
```js
158+
import { Modifier } from '@ember/modifiers';
159+
160+
export default class extends Modifier {
161+
this.listnerOptions = undefined;
162+
didInsertElement([ eventType, callback ], eventOptions) {
163+
this.listenerOptions = [
164+
eventType,
165+
callBack,
166+
eventOptions
167+
];
168+
this.element.addEventListener(eventType, callback, eventOptions);
169+
},
170+
171+
didUpdate([ eventType, callback ], eventOptions) {
172+
this.element.removeEventListener(...this.listenerOptions);
173+
this.element.addEventListener(eventType, callback, eventOptions);
174+
this.listnerOptions = [eventType, callback, eventOptions];
175+
}
176+
177+
willDestroyElement() {
178+
this.element.removeEventListener(...this.listenerOptions);
179+
}
180+
}
181+
```
182+
183+
This hook has the following timing semantics:
184+
185+
**Always**
186+
- called **after** any children modifier's `willDestroyElement` hook is called
187+
188+
**May or May Not**
189+
- be called in the same tick as DOM removal
190+
191+
## How we teach this
192+
193+
While user defined element modifiers are a new concept, Ember has had the [`{{action}}` modifier](https://www.emberjs.com/api/ember/release/classes/Ember.Templates.helpers/methods/action?anchor=action) since 1.0.0. We would need to update the existing documentation around `{{action}}` to refer to it as a modifier. In terms of documenting the modifier base class, I think we can largely repurpose existing documentation around [component's `didInsertElement`](https://guides.emberjs.com/release/components/the-component-lifecycle/#toc_integrating-with-third-party-libraries-with-didinsertelement) hook.
194+
195+
In terms of guides, I believe we should add a section to the "Templates" section to outline how to write modifiers. This would be similar to the ["Writing Helpers"](https://guides.emberjs.com/release/templates/writing-helpers/) guide.
196+
197+
## Drawbacks
198+
199+
The drawbacks of adding element modifiers largely deal with explaining when to use a classic Ember component for encapsulating some DOM manipulation versus when to use an element modifier. That being said it is likely that the recommendation would be to use element modifiers if you are just manually modifying the DOM.
200+
201+
This API also doesn't attempt to create a corollary of `this.element` for Glimmer Components and instead offers a different API for altering DOM nodes directly. This expands the surface area of Ember's API.
202+
203+
## Alternatives
204+
205+
The alternative to this is to create a "ref"-like API that is available in [other client side frameworks](https://reactjs.org/docs/refs-and-the-dom.html). This may look like the following:
206+
207+
```hbs
208+
<section>
209+
<h1 {{ref "heading"}}>Hello!</h1>
210+
<p>How are you?</p>
211+
</section>
212+
```
213+
214+
```js
215+
import Component from '@glimmer/component';
216+
217+
export class extends Component {
218+
headingNode = null;
219+
heading(headingElement) {
220+
if (headingElement) {
221+
this.headingElement = headingElement;
222+
headingElement.addEventListener('click', this.click);
223+
} else {
224+
this.headingElement.removeEventListener('click', this.click);
225+
this.headingElement = null;
226+
}
227+
}
228+
229+
click(evt) {
230+
evt.preventDefault();
231+
alert('click');
232+
}
233+
}
234+
```
235+
236+
This API would be implemented as a framework level modifier and would call hooks on the backing class with the element the `{{ref}}` was installed on. When the element is being removed the method would be called with `null`. It's the component author's responsibility to manage the DOM node.
237+
238+
This RFC does not close the door on a `{{ref}}`-like API, but rather exposes the primitives needed to create it.
239+
240+
## Unresolved questions
241+
242+
TBD?

0 commit comments

Comments
 (0)