Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the guides for element modifiers #1946

Merged
merged 2 commits into from
Aug 11, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 14 additions & 8 deletions guides/release/components/template-lifecycle-dom-and-modifiers.md
Original file line number Diff line number Diff line change
Expand Up @@ -293,10 +293,17 @@ The modifier that we're going to build will allow us to say:

Pretty nice, right?

To accomplish that, we'll create a modifier in `app/modifiers/autofocus.js`. First, install [`ember-modifier`](https://github.com/ember-modifier/ember-modifier) and then generate an `autofocus` modifier for your app:
New Ember apps ship with a dependency on
[ember-modifier](https://github.com/ember-modifier/ember-modifier), which
provides a friendly API for writing your own element modifiers. This library is
in turn based on a low level API named _modifier managers_. Managers are a
framework-development level feature, and not something most developers need to
interact with. You'll see in the following examples that the modifier API is
imported from the `ember-modifier` package.

First generate the `autofocus` modifier for your application:

```bash
ember install ember-modifier
ember generate modifier autofocus
```

Expand All @@ -308,9 +315,10 @@ import { modifier } from "ember-modifier";
export default modifier(element => element.focus());
```

And that's it!
And that's it! Now we can use our custom `{{autofocus}}` modifier throughout our application.

Now we can use our custom `{{autofocus}}` modifier throughout our application.
Read more about the `ember-modifier` APIs at [ember-modifiers:
Usage](https://github.com/ember-modifier/ember-modifier#usage).

## Communicating Between Elements in a Component

Expand Down Expand Up @@ -390,7 +398,6 @@ export default class AudioPlayerComponent extends Component {
That's it for the component: we're translating the user's interactions into _state_. Now we need to build a modifier to translate the state into the appropriate DOM method calls!

```bash
ember install ember-modifier
ember generate modifier play-when
```

Expand Down Expand Up @@ -448,12 +455,11 @@ document.addEventListener("click", event => {

The most important difference between this example and the cases we've seen so far is that we need to remove the `click` event handler from the document when this element is destroyed.

To accomplish this, we can use [`ember-modifier`](https://github.com/ember-modifier/ember-modifier) to create a `on-click-outside` modifier that sets up the event listener after the element is first inserted and removes the event listener when the element is removed.
To accomplish this, we can use [`ember-modifier`](https://github.com/ember-modifier/ember-modifier) (which is already installed in newly generated Ember apps) to create a `on-click-outside` modifier that sets up the event listener after the element is first inserted and removes the event listener when the element is removed.

Run the following commands to install the addon and generate a new modifier:
Generate the new modifier:

```bash
ember install ember-modifier
ember generate modifier on-click-outside
```

Expand Down
34 changes: 20 additions & 14 deletions guides/release/upgrading/current-edition/glimmer-components.md
Original file line number Diff line number Diff line change
Expand Up @@ -784,15 +784,17 @@ functionality that lifecycle hooks contained.

#### Writing your own modifiers

There are also community APIs available for writing your own modifiers, such as
[ember-modifier](https://github.com/ember-modifier/ember-modifier).
Ember itself has low level APIs known as _modifier managers_ which can be used
to write these higher level APIs. In general, it's recommended to use a
community addon to write modifiers, and _not_ to write your own modifier
manager.
New Ember apps ship with a dependency on
[ember-modifier](https://github.com/ember-modifier/ember-modifier), which
provides a friendly API for writing your own element modifiers. This library is
in turn based on a low level API named _modifier managers_. Managers are a
framework-development level feature, and not something most developers need to
interact with.

Let's see what our first example would look like if we were to write it as a
modifier using `ember-modifier`:
Custom modifiers based on the `ember-modifier` API can be a more expressive
interface for your logic, and can better encapsulate an implementation.

Let's write a modifier that implements adding an event listener.

```js {data-filename=app/modifiers/add-event-listener.js}
import { modifier } from 'ember-modifier';
Expand Down Expand Up @@ -825,12 +827,16 @@ export default class ScrollComponent extends Component {
</div>
```

This modifier generalizes the functionality that the component implemented using
lifecycle hooks before, so we can use this modifier whenever we need to in _any_
component. This is a much better solution than manually managing event listeners
every time we need one! At this point, the modifier is effectively the same as
the `{{on}}` modifier as well, so we could get rid of it altogether and replace
it with `on`:
The new `add-event-listener` modifier presents a more expressive interface to
the `hbs` template: There is only a single modifier to apply instead of two, the
implementation always tears down after itself upon teardown of the target element,
and the only JavaScript you have to write during re-user is the implementation
of the business logic.

At this point, it is worth noting that the custom `{{add-event-listener}}`
modifier is effectively a re-implementation of the Ember built-in `{{on}}`
modifier (See the
[documentation](https://api.emberjs.com/ember/5.1/classes/Ember.Templates.helpers/methods/on?anchor=on)). Using that built-in looks like:

```handlebars {data-filename=app/components/scroll-component.hbs}
<div {{on "scroll" this.listener}}>
Expand Down
Loading