Coming Quickly in Ember Octane

(This submit was initially printed on www.pzuraq.com)

Whats up once more, and welcome again! That is the fourth entry within the multipart Coming Quickly in Ember Octane collection, the place we’re previewing among the numerous options which can be touchdown in Ember’s upcoming Octane version, together with:

These aren’t all of the brand new options that shall be a part of Octane, simply those that I am most accustomed to personally. This collection is geared toward current Ember customers, however in case you’re new to Ember or tried Ember some time in the past and need to see how issues are altering, I will be offering context on the present options as we go alongside. These posts will not be doing deep dives on all the sting circumstances of the performance, they’re moreso meant as an outline of what is coming. If you happen to’re interested by what an version is strictly, you’ll be able to take a look at a fast break down in the primary submit within the collection.

Alright, now let’s discuss modifiers, Ember’s new software for working with the DOM!

What Are “Modifiers”

Modifiers are just like Handlebars helpers, they’re features or lessons that can be utilized in templates instantly utilizing {{double-curlies}}. The main distinction with modifiers is that they’re utilized on to parts:

<button {{on "click on" this.handleClick}}>
  Whats up, World!
</button>

Modifiers are used for manipulating or studying from the DOM in some way. As an example, the instance above makes use of the on modifier so as to add a click on handler to the button ingredient it’s modifying. On the whole modifiers act on the ingredient they’re modifying, however they may additionally act on the the subtree of that ingredient.

Modifiers aren’t a wholly new idea in Ember. In actual fact, they’ve existed in some type or one other since among the earliest days of Ember, within the type of the {{motion}} modifier, and the {{bind-attr}} modifier from the v1 period of the framework. Nevertheless, it is by no means been potential earlier than for customers to make their personal modifiers. Now they’re being given firstclass assist to permit customers extra constancy in how they work together with the DOM, and to permit DOM code to be extra simply shared throughout parts and different templates.

The New didInsertElement

It’s possible you’ll be considering, do not lifecycle hooks resolve the identical drawback? Cannot I put logic like including occasion listeners and measuring parts in didInsertElement or didRender on my element class and name it a day? Why do we’d like a brand new idea for this type of logic?

There are a number of causes modifiers find yourself being a greater answer for DOM manipulation typically:

1. They permit concentrating on particular parts extra simply. Lifecycle hooks solely mean you can work with the element’s root ingredient, if it has one. If you wish to goal another ingredient within the element, it may be a variety of work. As an example, to do the identical factor as our authentic instance with the on modifier, we must use querySelector in our didInsertElement hook to search out the button ingredient:

didInsertElement() {
  this.ingredient
    .querySelector('button')
    .addEventListener('click on', this.handleClick);
}

<button>Whats up, World!</button>

{{#if this.showTutorial}}
  <span class="tooltip">Click on the button!</span>
{{/if}}

didInsertElement() {
  this.ingredient
    .querySelector('button')
    .addEventListener('click on', this.handleClick);

  let tooltip = this.ingredient.querySelector('.tooltip');

  if (tooltip) {
    tooltip.addEventListener('mouseover', this.toggleTooltip);
  }
}

<button {{on "click on" this.handleClick}}>
  Whats up, World!
</button>

{{#if this.showTutorial}}
  <span class="tooltip" {{on "mouseover" this.toggleTooltip}}>
    Click on the button!
  </span>
{{/if}}

class HelloWorld extends Element {
  addTooltipListener() {
    // save the ingredient so we are able to take away the listener later
    this._tooltip = this.ingredient.querySelector('.tooltip');

    if (this._tooltip) {
      this._tooltip.addEventListener(
        'mouseover',
        this.toggleTooltip
      );
    }
  }

  removeTooltipListener() {
    if (this._tooltip) {
      this._tooltip.removeEventListener(
        'mouseover',
        this.toggleTooltip
      );
    }
  }

  didInsertElement() {
    this.ingredient
      .querySelector('button')
      .addEventListener('click on', this.handleClick);

    this.addTooltipListener();
  }

  didUpdate() {
    this.removeTooltipListener();
    this.addTooltipListener();
  }

  willDestroyElement() {
    this.ingredient
      .querySelector('button')
      .removeEventListener('click on', this.handleClick);

    this.removeTooltipListener();
  }

  // ...
}

3. They make sharing code between parts a lot simpler. Typically instances the identical varieties of DOM manipulations should be utilized in many parts all through an app, and often it is not straightforward or pure to share them by way of class inheritance. However, utility features typically really feel very bloated and boilerplate heavy to make use of for these functions, since they should use state from the element and be built-in into its hooks. Addons like ember-lifeline do job at decreasing the boilerplate, however it’s nonetheless not supreme.

This is without doubt one of the remaining use circumstances for Ember’s mixin performance, and arguably modifiers resolve it much more cleanly because the modifications are utilized the place they occur.

4. They work with template-only parts. At the moment you need to all the time create a element class to do even easy DOM manipulation. With modifiers that is not obligatory. Sooner or later, this can imply extra efficiency wins for less complicated parts, since they will not want a category occasion.

5. They work with tag-less parts and Glimmer parts. At the moment, tag-less parts (parts with tagName: '') have lifecycle hooks, however they do not have the this.ingredient property since they do not have a wrapping ingredient. Because of this manipulating the DOM in them is fairly onerous, you typically have so as to add a singular id to a component and choose by that. Glimmer parts additionally do not have this.ingredient since they do not have a wrapping ingredient both (extra on that subsequent time), and on prime of that, additionally they do not have any lifecycle hooks past the constructor and willDestroy.

Modifiers disconnect the element class definition from DOM manipulation, which implies that they work even with out these APIs. In actual fact, they may work with any element API. This enables extra thorough separation considerations, and makes transitioning ahead from basic parts to Glimmer parts even simpler.

These advantages are the reasoning behind introducing a brand new idea. We additionally aren’t the one framework to have observed the advantages of this sample, most not too long ago React’s new Hooks API is conducting a variety of the identical targets in an analogous method, particularly the useLayoutEffect hook which is particularly for operating side-effecting structure code. Ember modifiers fill an analogous hole.

So What Do They Look Like?

The utilization facet of modifiers has been outlined since Ember v1. A modifier is identical syntax as a helper, however utilized on to a component as an alternative of to an attribute:

<div
  {{my-modifier 'howdy' 'world!'}}
  position={{my-helper 'some' 'worth'}}
></div>

<!-- that is the motion modifier -->
<div {{motion this.handleClick}}></div>

<!-- that is the motion helper -->
<div onclick={{motion this.handleClick}}></div>

export default class DarkMode extends Modifier {
  @service userSettings;

  didInsert(ingredient, [darkModeClass]) {
    if (this.userSettings.darkModeEnabled) {
      this._previousDarkModeClass = darkModeClass;
      ingredient.classList.add(darkModeClass);
    }
  }

  willDestroy(ingredient) {
    ingredient.classList.take away(this._previousDarkModeClass);
  }

  didUpdate() {
    this.willDestroy(...arguments);
    this.didInsert(...arguments);
  }
}

<!-- utilization -->
<div {{dark-mode 'ui-dark'}}></div>

operate darkMode(userSettings, ingredient, [darkModeClass]) {
  if (userSettings.darkModeEnabled) {
    ingredient.classList.add(darkModeClass);

    return () => {
      ingredient.classList.take away(darkModeClass);
    };
  }
}

export default modifier(
  { companies: ['userSettings'] },
  darkMode
);

<!-- utilization -->
<div {{dark-mode 'ui-dark'}}></div>

@modifier
operate darkMode(
  @service userSettings,
  ingredient,
  [darkModeClass]
) {
  if (userSettings.darkModeEnabled) {
    ingredient.classList.add(darkModeClass);

    return () => {
      ingredient.classList.take away(darkModeClass);
    }
  }
}

• ember-on-modifier, created by Jan Buschtöns, permits you to add occasion listeners of any variety on to parts. This implies you’ll be able to cleanup any ember-lifeline code you’ve mendacity round and change on over!
• ember-ref-modifier, created by Alex Kanunnikov, mimics React’s “ref” system for storing references to parts. This lets you use them in your element instantly if it’s essential to, for extra sophisticated element use circumstances.

If you happen to’re prepared to work at a decrease degree and experiment with new APIs, you can too take a look at the modifier-manager-polyfill, however be warned that it’s meant for low degree infrastructure, and should not typically be used to write down modifiers instantly. The Modifier Supervisor API remains to be very new, and it will take a while to solidify the userland APIs, however they’re going to be accessible quickly!

Placing It All Collectively

As all the time, we’ll finish with an instance of a element earlier than and after, to see how this new characteristic impacts actual functions. This time we’ll use an instance from ember-paper, the Materials UI addon for Ember, particularly the paper-toast-inner element, which makes use of the Hammer.js library for recognizing contact occasions.

We’ll even be utilizing theoretical consumer APIs this time round, as a result of the main points of writing a element supervisor are undoubtedly not ergonomic.

NOTE: These examples comprise PROPOSED APIs that haven’t been finalized, and will change sooner or later.

Beginning out, that is what our element appears to be like like:

import Element from '@ember/element';

import { run } from '@ember/runloop';
import { computed } from '@ember/object';
import { htmlSafe } from '@ember/string';
import structure from '../templates/parts/paper-toast-inner';
import TransitionMixin from 'ember-css-transitions/mixins/transition-mixin';
import { invokeAction } from 'ember-invoke-action';

/**
 * @class PaperToastInner
 * @extends Ember.Element
 */
export default Element.lengthen(TransitionMixin, {
  structure,
  tagName: 'md-toast',

  // ...

  _setupHammer() {
    // Allow dragging the slider
    let containerManager = new Hammer.Supervisor(this.ingredient, {
      dragLockToAxis: true,
      dragBlockHorizontal: true,
    });
    let swipe = new Hammer.Swipe({
      route: Hammer.DIRECTION_ALL,
      threshold: 10,
    });
    let pan = new Hammer.Pan({
      route: Hammer.DIRECTION_ALL,
      threshold: 10,
    });
    containerManager.add(swipe);
    containerManager.add(pan);
    containerManager
      .on('panstart', run.bind(this, this.dragStart))
      .on('panmove', run.bind(this, this.drag))
      .on('panend', run.bind(this, this.dragEnd))
      .on('swiperight swipeleft', run.bind(this, this.dragEnd));
    this._hammer = containerManager;
  },

  didInsertElement() {
    this._super(...arguments);
    if (this.get('swipeToClose')) {
      this._setupHammer();
    }
  },

  didUpdateAttrs() {
    this._super(...arguments);

    if (this.get('swipeToClose') && !this._hammer) {
      // whether it is enabled and we did not init hammer but
      this._setupHammer();
    } else if (!this.get('swipeToClose') && this._hammer) {
      // whether it is disabled and we did init hammer already
      this._teardownHammer();
    }
  },

  willDestroyElement() {
    this._super(...arguments);
    if (this._hammer) {
      this._teardownHammer();
    }
  },

  _teardownHammer() {
    this._hammer.destroy();
    delete this._hammer;
  },

  dragStart(occasion) {
    // ...
  },

  drag(occasion) {
    // ...
  },

  dragEnd() {
    // ...
  },
});

// /addon/modifiers/if.js
operate _if(
  ingredient,
  [conditional, modifier, ...rest],
  named) {
  if (Boolean(conditional)) {
    return modifier(ingredient, relaxation, named);
  }
}

export default modifier(_if);

// /addon/modifiers/hammer.js
const HAMMER_TYPE = {
  swipe: Hammer.Swipe,
  pan: Hammer.Pan,
  // remaining sorts...
};

const HAMMER_DIRECTION = {
  all: Hammer.DIRECTION_ALL,
  // remaining instructions...
};

operate hammer(ingredient, positional, {
  recognizers = [],
  choices = {},
  ...occasions
}) {
  let hammer = new Hammer.Supervisor(ingredient, choices);

  for (let { sort, route, ...relaxation } of recognizers) {
    let Recognizer = HAMMER_TYPE[type];
    route = HAMMER_DIRECTION[direction];

    hammer.add(new Recognizer({ route, ...relaxation }));
  }

  for (let occasion in occasions) {
    hammer.on(occasion, occasions[event]);
  }

  return () => {
    hammer.destroy();
  };
}

export default modifier(hammer);

import Element from '@ember/element';
import template from '../templates/parts/paper-toast-inner';
import TransitionMixin from 'ember-css-transitions/mixins/transition-mixin';

import { structure, tagName } from '@ember-decorators/element';

/**
 * @class PaperToastInner
 * @extends Ember.Element
 */
@tagName('')
@structure(template)
export default class PaperToastInner extends Element.lengthen(TransitionMixin) {
  // ...

  dragStart(occasion) {
    // ...
  }

  drag(occasion) {
    // ...
  }

  dragEnd() {
    // ...
  }
}

<md-toast
  {{if @swipeToClose hammer

    panstart=this.dragStart
    panmove=this.drag
    panend=this.dragEnd
    swiperight=this.dragEnd
    swipeleft=this.dragEnd

    recognizers=(arr
      (hash sort="swipe" route="all" threshold=10)
      (hash sort="pan" route="all" threshold=10)
    )

    choices=(hash
      dragLockToAxis=true
      dragBlockHorizontal=true
    )
  }}
>
  ...
</md-toast>

// /addon/modifiers/horizontal-swipe.js
import hammer from './hammer';

export default modifier((ingredient, positional, named) => {
  return hammer(ingredient, positional, {
    ...named,

    recognizers: [
      { type: 'swipe', direction: 'all', threshold: 10 }
      { type: 'pan', direction: 'all', threshold: 10 }
    ],

    choices: {
      dragLockToAxis: true,
      dragBlockHorizontal: true,
    },
  });
});

<md-toast
  {{if @swipeToClose horizontalSwipe

    panstart=this.dragStart
    panmove=this.drag
    panend=this.dragEnd
    swiperight=this.dragEnd
    swipeleft=this.dragEnd
  }}
>
  ...
</md-toast>

Modifiers are some of the thrilling options touchdown in Octane to me. They undoubtedly are a shift within the psychological mannequin for DOM and lifecycle hooks, however in my expertise to date the element’s I’ve refactored with them are a lot simpler to motive about, and far more composable. Nailing down the userland APIs goes to be an thrilling and attention-grabbing a part of the design, and I am hoping we get some attention-grabbing new concepts from the neighborhood (and if anybody needs to implement both of the managers I’ve described, please do! The category primarily based one has even been largely spec’d out in Chad Hietala’s RFC. Ping me in Discord if you would like assist!) Total, I am trying ahead to seeing how they prove 😄

That is all I’ve for this week! Subsequent Friday would be the final submit on this collection – Glimmer parts, the subsequent technology of parts in Ember.