/ #JavaScript #VueJS 

A simple, real-world Vue.js directive example

Vue.js is “The Progressive JavaScript Framework”. It takes inspiration from all prior art in the view library and frontend framework world, including AngularJS, React, Angular, Ember, Knockout and Polymer. In Vue (and Angular/AngularJS), a directive is a way to wrap functionality that usually applies to DOM elements. The example in Vue’s documentation is a focus directive.

When running Vue.js inside of AngularJS, an issue occured whereby the AngularJS router would try to resolve normal anchors’ href on click. The hrefs weren’t AngularJS URLs so it would fall back to the default page. One solution could have leveraged components to update window.location directly, but here’s a nifty directive to do the same:

<a v-href="'/my-url'">Go</a>

That’s a pretty cool API, and it’s probably more idiomatic Vue than:

<MyAnchor href="/my-url">
  Go
</MyAnchor>

There were a couple of gotchas:

Table of Contents

Local vs global directive registration 🌐

A global Vue directive can be defined like so:

Vue.directive("non-angular-link", {
  // directive definition
});

It can also be defined locally as follows:

Vue.component("my-component", {
  directives: {
    "non-angular-link": nonAngularLinkDirective
  }
});

Where nonAngularLinkDirective would be a JavaScript object that defines the directive, eg.

const nonAngularLinkDirective = {
  bind(el, binding) {},
  unbind(el) {}
};

This allows for flexibility if using a bundler like webpack and single file components:

// non-angular-link-directive.js
export const nonAngularLinkDirective = {
  // directive definition
};
// MyComponent.vue
<template>
  <a
    href="/my-url"
    v-non-angular-link
  >
    Go
  </a>
</template>

<script>
import { nonAngularDirective } from './non-angular-link.directive';
export default {
  directives: {
    'non-angular-link': nonAngularLinkDirective
  }
};
</script>

A minimal directive API 👌

A full MyAnchor single file component would look like the following:

// MyAnchor.vue
<template>
  <a
    @click="goToUrl($event)"
    :href="href"
  >
    <slot />
  </a>
</template>
<script>
export default {
  props: {
    href: {
      type: String,
      required: true
    }
  },
  methods: {
    goToUrl(e) {
      e.preventDefault();
      window.location.assign(this.href);
    }
  }
});
</script>

This is quite verbose and leverages a global DOM object… not ideal. Here’s something similar using a directive:

// non-angular-link-directive.js
export const nonAngularLinkDirective = {
  bind(el) {
    el.addEventListener("click", event => {
      event.preventDefault();
      window.location.assign(event.target.href);
    });
  }
};

This directive has to be used like so <a href="/my-url" v-non-angular-link>Go</a>, which isn’t the nicest API. By leveraging the second parameter passed to bind we can write it so that it can be used like <a v-href="'/my-url'">Go</a> (for more information about el and binding, see https://vuejs.org/v2/guide/custom-directive.html#Directive-Hook-Arguments):

// non-angular-link-directive.js
export const nonAngularLinkDirective = {
  bind(el, binding) {
    el.href = binding.value;
    el.addEventListener("click", event => {
      event.preventDefault();
      window.location.assign(event.target.href);
    });
  }
};

We can now use it like using a local directive definition:

// MyComponent.vue
<template>
  <a v-href="'/my-url'">Go</a>
</template>
<script>
import { nonAngularLinkDirective } from './non-angular-link.directive';
export default {
  directives: {
    href: nonAngularLinkDirective
  }
};
</script>

Vue directive hooks and removeEventListener 🆓

For the full list of directive hooks, see https://vuejs.org/v2/guide/custom-directive.html#Hook-Functions.

As a good practice, the event listener should be removed when it’s not required any more. This can be done in unbind much in the same way as it was added, there’s a catch though, the arguments passed to removeEventListener have to be the same as the ones passed to addEventListener:

// non-angular-link-directive.js
const handleClick = event => {
  event.preventDefault();
  window.location.assign(event.target.href);
};
export const nonAngularLinkDirective = {
  bind(el, binding) {
    el.href = binding.value;
    el.addEventListener("click", handleClick);
  },
  unbind(el) {
    el.removeEventListener("click", handleClick);
  }
};

This will now remove the listener when the component where the directive is used is destroyed/un-mounts and leaves us with no hanging listeners.

Handling clicks properly 🖱

An edge case happens when an anchor contains an image: the target of the event is not the anchor, but the img… which doesn’t have a href attribute.

To deal with this, with a little knowledge of how addEventListener calls the passed handler, we can refactor the handleClick function.

// non-angular-link-directive.js
function handleClick(event) {
  // The `this` context is the element
  // on which the event listener is defined.
  event.preventDefault();
  window.location.assign(this.href);
}

// rest stays the same

By using a named functions and the this allows the event listener to bind this to the element on which it’s attached as opposed to the lexical this of an arrow function.

Parting thoughts 📚

We use window.location.assign so as to allow to test easily. With Jest and @vue/test-utils a test at the component level should look like this:

import { shallowMount } from '@vue/test-utils';
import MyComponent from './MyComponent.vue';

test('It should call window.location.assign with the right urls', () => {
  // Stub window.location.assign
  window.location.assign = jest.fn();

  const myComponent = shallowMount(MyComponent);

  myComponent.findAll('a').wrappers.forEach((anchor) => {
    const mockEvent = {
      preventDefault: jest.fn()
    };
    anchor.trigger('click', mockEvent);
    expect(mockEvent.preventDefault).toHaveBeenCalled();
    expect(window.location.assign).toHaveBeenCalledWith(
      anchor.attributes().href
    );
});

Directives allow you to contain pieces of code that interact with the DOM. This code needs to be generic enough to be used with the limited information available to a directive.

By coding against the DOM, we leverage the browser APIs instead of re-inventing them.

Cover photo by frank mckenna on Unsplash

Looking for a new job? Take Triplebyte’s quiz and have top tech companies pitch you!

Author

Hugo Di Francesco

A Software Engineer who is big on Node.js, queues and Vue(s). Co-author of "Professional JavaScript" with Packt. He shares practical JavaScript tips for the developer who wants to get things done on Code with Hugo. University College London (UCL), MEng Mathematical Computation Graduate.

Get Testing Superpowers with these Underused Jest Features

Subscribe for free resources that turbocharge your Jest tests and a discount on the "Advanced Jest Handbook"