diff --git a/text/0373-Element-Modifier-Managers.md b/text/0373-Element-Modifier-Managers.md index b372be21e4..cb98a99ad5 100644 --- a/text/0373-Element-Modifier-Managers.md +++ b/text/0373-Element-Modifier-Managers.md @@ -16,13 +16,13 @@ project-link: ## Summary -This RFC proposes a low-level primitive for defining element modifiers. It is a parent to the [Modifiers RFC](https://github.com/emberjs/rfcs/pull/353). +This RFC proposes a low-level primitive for defining element modifiers. It is a parent to the [Element Modifiers RFC](https://github.com/emberjs/rfcs/pull/811). ## Motivation Ever since Ember 1.0 we have had the concept of element modifiers, however Ember only exposes one modifier; `{{action}}`. We also do not provide a mechanism for defining your own modifiers and managing their life cycles. -As [pointed out](https://github.com/emberjs/rfcs/pull/353#issuecomment-417769349) in the [Element Modifiers RFC](https://github.com/emberjs/rfcs/pull/353) we should expose the underlying infrastructure that makes element modifiers possible. Based on our experience, we believe it would be beneficial to open up these new primitives to the wider community. The largest benefit is that it allows the community to experiment with and iterate on APIs outside of the core framework. +As [pointed out](https://github.com/emberjs/rfcs/pull/353#issuecomment-417769349) in the original [Modifiers RFC](https://github.com/emberjs/rfcs/pull/353) we should expose the underlying infrastructure that makes element modifiers possible. Based on our experience, we believe it would be beneficial to open up these new primitives to the wider community. The largest benefit is that it allows the community to experiment with and iterate on APIs outside of the core framework. This RFC is in the same spirit as the [custom components RFC](https://github.com/emberjs/rfcs/blob/master/text/0213-custom-components.md). @@ -458,7 +458,8 @@ What is proposed in this RFC is a low-level primitive. We do not expect most use In the long term, there is a risk of fragmentating the Ember ecosystem with many competing modifier APIs. However, given the Ember community's strong desire for conventions, this seems unlikely. We expect this to play out similar to the data-persistence story – there will be a primary way to do things (Ember Data), but there are also plenty of other alternatives catering to niche use cases that are underserved by Ember Data. ## Alternatives -Instead of focusing on exposing enough low-level primitives we can just ship the high level API as described in [RFC#353](https://github.com/emberjs/rfcs/pull/353). +Instead of focusing on exposing enough low-level primitives we can just ship the high level API as described in [RFC#811](https://github.com/emberjs/rfcs/pull/811). + ## Unresolved questions TBD? diff --git a/text/0811-element-modifiers.md b/text/0811-element-modifiers.md new file mode 100644 index 0000000000..5d46f60a77 --- /dev/null +++ b/text/0811-element-modifiers.md @@ -0,0 +1,281 @@ +--- +stage: accepted +start-date: 2022-03-29T00:00:00.000Z +release-date: +release-versions: +teams: # delete teams that aren't relevant + - cli + - learning +prs: + accepted: https://github.com/emberjs/rfcs/pull/811 +project-link: +--- + + + +# Element Modifiers + +## Summary + +This RFC introduces the concept of user defined element modifiers and proposes +adding [ember-modifier](https://github.com/ember-modifier/ember-modifier) +to the blueprint that back `ember new`, providing an +officially-supported path for using modifiers out of the box. + +This RFC supersedes the original [RFC #353 "Modifiers"][rfc-0353]. + +## Motivation + +Ember Octane introduced Glimmer Components as a replacement for Classic +Components. They are simpler, more ergonomic, and more declarative. In contrast +with Classic Components, Glimmer Components don't have any element/DOM based +properties or hooks giving access to DOM. This was an intentional move as +component backing class gets disconnected from DOM manipulation. + +Modifiers are similar to template helpers: they are functions or classes that can be used +in templates directly using `{{double-curlies}}` syntax. The major difference with modifiers +is that they are applied directly to *elements*: + +```handlebars + +``` + +This RFC builds on top of low-level primitives for defining element modifiers +introduced in [RFC #373 "Element Modifier Manager"][rfc-0373]. +The `ember-modifier` addon was built on top of those low-level primitives and +provides a convenient API for authoring element modifiers in Ember. + +Element Modifiers were introduced as part of Ember Octane edition and are first class citizens +in Ember application, like components or helpers. However today, developers need to install +an additional library to be able to define custom modifiers. + +This RFC seeks to fill this gap in Ember.js' development mental model by +providing `ember-modifier` in the blueprint. `ember-modifier` will be added +to `devDependencies`, same as e.g. @glimmer/component. + +A basic element modifier is defined with the type of `modifier`. +For example these paths would be global element modifiers in an application: + +* `app/modifiers/draggable.js` +* `app/modifiers/effect.js` + +Similar to helpers, modifiers can be function-based: + +```js +// /app/modifiers/on.js +import { modifier } from 'ember-modifier'; + +export default modifier((element, [eventName, handler]) => { + element.addEventListener(eventName, handler); + + return () => { + element.removeEventListener(eventName, handler); + } +}); +``` + +or class-based + +```ts +// /app/modifiers/on.js +import Modifier from 'ember-modifier'; +import { registerDestructor } from '@ember/destroyable'; + +function cleanup(instance: OnModifier) { + let { element, event, handler } = instance; + + if (element && event && handler) { + element.removeEventListener(event, handler); + + instance.element = null; + instance.event = null; + instance.handler = null; + } +} + +export default class OnModifier extends Modifier { + element = null; + event = null; + handler = null; + + // Manage teardown + constructor() { + super(...arguments); + registerDestructor(this, cleanup); + } + + // Run on installation and all changes to tracked state. + modify(element, [event, handler]) { + // Clear any previous state. + cleanup(this); + + // Set up the new handling. + this.addEventListener(element, event, handler); + } + + // methods for reuse + addEventListener(element, event, handler) { + // Store the current element, event, and handler for when we need to remove + // them during cleanup. + this.element = element; + this.event = event; + this.handler = handler; + + element.addEventListener(event, handler); + }; +} +``` + +While this is slightly more complicated than the function-based version, +that complexity comes along with much more *control*. It also allows us to hook +into Ember's dependency injection system, for example to use services. + +[RFC #432: Contextual Helpers and Modifiers][rfc-0432] allows optional +invocation and partial application of modifiers, and allows modifiers to be +yielded, passed as arguments, etc. [RFC #779: First-Class Component +Templates][rfc-0779] allows defining them locally or importing them directly to +be used in a `