ember-modifier


`

`js
// app/components/scroll-container.js

import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { action } from '@ember/object';

export default class ScrollContainerComponent extends Component {
@tracked scrollPosition = 0;

@action scrollToTop() {
this.scrollPosition = 0;
}
}
`

`handlebars
{{!-- app/templates/application.hbs --}}


A lot of content...

Back To Top

`

#### Example with Cleanup

If the functionality you add in the modifier needs to be torn down when the
modifier is removed, you can use registerDestructor from @ember/destroyable.

For example, if you want to have your elements dance randomly on the page using
setInterval, but you wanted to make sure that was canceled when the modifier
was removed, you could do this:

`js
// app/modifiers/move-randomly.js

import Modifier from 'ember-modifier';
import { registerDestructor } from '@ember/destroyable'

const { random, round } = Math;
const DEFAULT_DELAY = 1000;

function cleanup(instance) {
if (instance.setIntervalId !== null) {
clearInterval(instance.setIntervalId);
instance.setIntervalId = null;
}
}

export default class MoveRandomlyModifier extends Modifier {
element = null;
setIntervalId = null;

constructor(owner, args) {
super(owner, args);
registerDestructor(this, cleanup);
}

modify(element, _, { delay }) {
// Save off the element the first time for convenience with #moveElement
if (!this.element) {
this.element = element;
}

// Reset from any previous state.
cleanup(this);

this.setIntervalId = setInterval(this.#moveElement, delay ?? DEFAULT_DELAY);
}

#moveElement = (element) => {
let top = round(random() * 500);
let left = round(random() * 500);
this.element.style.transform = translate(${left}px, ${top}px);
};
}
`

Usage:

`hbs



`

#### Example with Service Injection

You can also use services into your modifier, just like any other class in Ember.

For example, suppose you wanted to track click events with ember-metrics:

`js
// app/modifiers/track-click.js

import { inject as service } from '@ember/service';
import Modifier from 'ember-modifier';
import { registerDestructor } from '@ember/destroyable';

function cleanup(instance) {
instance.element?.removeEventListener('click', instance.onClick, true);
}

export default class TrackClick extends Modifier {
@service metrics;

constructor(owner, args) {
super(owner, args);
registerDestructor(this, cleanup);
}

modify(element, [eventName], options) {
this.element = element;
this.eventName = eventName;
this.options = options;

cleanup();
element.addEventListener('click', this.onClick, true);
}

onClick = () => {
this.metrics.trackEvent(this.eventName, this.options);
};
}
`

Usage:

`hbs

Click Me!

`

#### API

constructor(owner, args)

Constructor for the modifier. You must call super(...arguments) before performing other initialization.

modify(element, positionalArgs, namedArgs)

The primary hook for running a modifier. It gets called when the modifier is installed on the element, and any time any tracked state it uses changes. That tracked state can be from its arguments, which are auto-tracked, or from any other kind of tracked state, including but not limited to state on injected services.

TypeScript

Both the function- and class-based APIs can be used with TypeScript!

Before checking out the Examples with Typescript below, there is an important caveat you should understand about type safety!

There are, today, two basic approaches you can take to dealing with your modifier's arguments and element in a type safe way:

1. You can use a type definition which specifies those for the outside world, relying on tooling like [Glint][glint] to check that the invocation is correct, and treat input as safe accordingly.
2. You can provide the minimal public interface which all modifiers conform to, and do runtime type checking with assert calls to make your internal implementation safe.

If you have a code base which is strictly typed from end to end, including with template type checking via Glint, then (1) is a great choice. If you have a mixed code base, or are publishing an addon for others to use, then [it's usually best to do both (1) and (2)][safe-ts-libs]!

[glint]: https://github.com/typed-ember/glint
[safe-ts-libs]: https://v5.chriskrycho.com/journal/writing-robust-typescript-libraries/s

To handle runtime checking, for non-type-checked templates (including projects not yet using Glint or supporting external callers), you should act as though the arguments passed to your modifier can be anything. They’re typed as unknown by default, which means by default TypeScript will require you to work out the type passed to you at runtime. For example, with the ScrollPositionModifier shown above, you can combine TypeScript’s [type narrowing] with the default types for the class to provide runtime errors if the caller passes the wrong types, while providing safety throughout the rest of the body of the modifier. Here, modify would be guaranteed to have the correct types for scrollPosition and relative:

[type narrowing]: https://www.typescriptlang.org/docs/handbook/advanced-types.html#type-guards-and-differentiating-types

`ts
import Modifier from 'ember-modifier';
import { assert } from '@ember/debug';

export class ScrollPositionModifier extends Modifier {
modify(element, [scrollPosition], { relative }) {
assert(,
first argument to 'scroll-position' must be a number, but ${scrollPosition} was ${typeof scrollPosition},
typeof scrollPosition === "number"
);

assert(
'relative' argument to 'scroll-position' must be a boolean, but ${relative} was ${typeof relative},
typeof relative === "boolean"
);

if (relative) {
element.scrollTop += scrollPosition;
} else {
element.scrollTop = scrollPosition;
}
}
}
`

If you were writing for a fully-typed context, you can define your Modifier with a Signature interface, similar to the way you would define your signature for a Glimmer Component:

`ts
// app/modifiers/scroll-position.ts
import Modifier from 'ember-modifier';

interface ScrollPositionModifierSignature {
Args: {
Positional: [number];
Named: {
relative: boolean;
};
};
}

export default class ScrollPositionModifier
extends Modifier {
modify(element, [scrollPosition], { relative }) {
if (relative) {
element.scrollTop += scrollPosition;
} else {
element.scrollTop = scrollPosition;
}
}
}
`

Besides supporting integration with [Glint][glint], this also provides nice hooks for documentation tooling. Note, however, that it can result in much worse feedback in tests or at runtime if someone passes the wrong kind of arguments to your modifier and you haven't included assertions: users who pass the wrong thing will just have the modifier fail. For example, if you fail to pass the positional argument, scrollPosition would simply be undefined, and then element.scrollTop could end up being set to NaN. Whoops! For that reason, if your modifier will be used by non-TypeScript consumers, you should both publish the types for it and add dev-time assertions:

`ts
// app/modifiers/scroll-position.ts
import Modifier from 'ember-modifier';

interface ScrollPositionModifierSignature {
Args: {
Positional: [scrollPosition: number];
Named: {
relative: boolean;
};
};
Element: Element; // not required: it'll be set by default
}

export default class ScrollPositionModifier
extends Modifier {
modify(element, [scrollPosition], { relative }) {
assert(,
first argument to 'scroll-position' must be a number, but ${scrollPosition} was ${typeof scrollPosition},
typeof scrollPosition === "number"
);

assert(
'relative' argument to 'scroll-position' must be a boolean, but ${relative} was ${typeof relative},
typeof relative === "boolean"
);

if (relative) {
element.scrollTop += scrollPosition;
} else {
element.scrollTop = scrollPosition;
}
}
}
`

$3

The Signature for a modifier is the combination of the positional and named arguments it receives and the element to which it may be applied.

`ts
interface Signature {
Args: {
Named: {
[argName: string]: unknown;
};
Positional: unknown[];
};
Element: Element;
}
`

When writing a signature yourself, all of those are optional: the types for modifiers will fall back to the correct defaults of Element, an object for named arguments, and an array for positional arguments. You can apply a signature when defining either a function-based or a class-based modifier.

In a function-based modifier, the callback arguments will be inferred from the signature, so you do not need to specify the types twice:

`ts
interface MySignature {
Element: HTMLMediaElement;
Args: {
Named: {
when: boolean;
};
Positional: [];
};
}

const play = modifier((el, _, { when: shouldPlay }) => {
if (shouldPlay) {
el.play();
} else {
el.pause();
}
})
`

You never need to specify a signature in this way for a function-based modifier: you can simply write the types inline instead:

`ts
const play = modifier(
(el: HTMLMediaElement, _: [], { when: shouldPlay }: { when: boolean}) => {
if (shouldPlay) {
el.play();
} else {
el.pause();
}
}
);
`

However, the explicit modifier(...) form is tested to keep working, since it can be useful for documentation!

The same basic approach works with a class-based modifier:

`ts
interface MySignature {
// ...
}

export default class MyModifier extends Modifier {
// ...
}
`

In that case, the element and args will always have the right types throughout the body. Since the type of args in the constructor are derived from the signature, you can use the ArgsFor type helper to avoid having to write the type out separately:

`ts
import Modifier, { ArgsFor } from 'ember-modifier';

interface MySignature {
// ...
}

export default class MyModifier extends Modifier {
constructor(owner: unknown, args: ArgsFor) {
// ...
}
}
`

ArgsFor isn't magic: it just takes the Args from the Signature you provide and turns it into the right shape for the constructor: the Named type ends up as the named field and the Positional type ends up as the type for args.positional, so you could write it out yourself if you preferred:

`ts
import Modifier from 'ember-modifier';

interface MySignature {
// ...
}

export default class MyModifier extends Modifier {
constructor(
owner: unknown,
args: {
named: MySignature['Args']['Named'];
positional: MySignature['Args']['Positional'];
}
) {
// ...
}
}
`

$3

#### Function-based modifier

Let’s look at a variant of the move-randomly example from above, implemented in TypeScript, and now requiring a named argument, the maximum offset. Using the recommended combination of types and runtime type-checking, it would look like this:

`ts
// app/modifiers/move-randomly.js
import { modifier } from 'ember-modifier';
import { assert } from '@ember/debug';

const { random, round } = Math;

export default modifier(
(element: HTMLElement, _: [], named: { maxOffset: number }
) => {
assert(
'move-randomly can only be installed on HTML elements!',
element instanceof HTMLElement
);

const { maxOffset } = named;
assert(
The 'max-offset' argument to 'move-randomly' must be a number, but was ${typeof maxOffset},
typeof maxOffset === "number"
);

const id = setInterval(() => {
const top = round(random() * maxOffset);
const left = round(random() * maxOffset);
element.style.transform = translate(${left}px, ${top}px);
}, 1000);

return () => clearInterval(id);
});
`

A few things to notice here:

1. TypeScript correctly infers the base types of the arguments for the function passed to the modifier; you don't need to specify what element or positional or named are unless you are doing like we are in this example and providing a usefully more-specific type to callers.

2. If we returned a teardown function which had the wrong type signature, that would also be an error.

If we return a value instead of a function, for example:

`ts
export default modifier((element, _, named) => {
// ...

return id;
});
`

TypeScript will report:

> `
> Type 'Timeout' is not assignable to type 'void | Teardown'.
> `

Likewise, if we return a function with the wrong signature, we will see the same kinds of errors. If we expected to receive an argument in the teardown callback, like this:

`ts
export default modifier((element, _, named) => {
//

return (interval: number) => clearTimeout(interval);
});
`

TypeScript will report:

> `
> Type '(interval: number) => void' is not assignable to type 'void | Teardown'.
> `

#### Class-based

To support correctly typing args in the constructor for the case where you do runtime type checking, we supply an ArgsFor type utility. (This is useful because the Signature type, matching Glimmer Component and other "invokable" items in Ember/Glimmer, has capital letters for the names of the types, while args.named and args.positional are lower-case.) Here’s how that would look with a fully typed modifier that alerts "This is a typesafe modifier!" an amount of time after receiving arguments that depends on the length of the first argument and an optional multiplier (a nonsensical thing to do, but one that illustrates a fully type-safe class-based modifier):

`ts
import Modifier, { ArgsFor, PositionalArgs, NamedArgs } from 'ember-modifier';
import { assert } from '@ember/debug';

interface NeatSignature {
Args: {
Named: {
multiplier?: number;
};
Positional: [string];
}
}


function cleanup(instance: Neat) => {
if (instance.interval) {
clearInterval(instance.interval);
}
}

export default class Neat extends Modifier {
interval?: number;

constructor(owner: unknown, args: ArgsFor) {
super(owner, args);
registerDestructor(this, cleanup);
}

modify(
element: Element,
[lengthOfInput]: PositionalArgs,
{ multiplier }: NamedArgs
) {
assert(
positional arg must be 'string' but was ${typeof lengthOfInput},
typeof lengthOfInput === 'string'
);

assert(
'multiplier' arg must be a number but was ${typeof multiplier},
multiplier ? typeof multiplier === "number" : true
);

multiplier = modifier ?? 1000;

let updateTime = multiplier * lengthOfInput;
this.interval = setInterval(() => {
element.innerText =
Behold, a type safe modifier moved after ${updateTime / 1000}s;
}, updateTime)
}
}
``

Contributing
------------------------------------------------------------------------------

See the Contributing guide for details.

License
------------------------------------------------------------------------------

This project is licensed under the MIT License.