DEV Community

Cover image for A simple, real-world Vue.js directive
Hugo Di Francesco
Hugo Di Francesco

Posted on • Originally published at codewithhugo.com on

A simple, real-world Vue.js directive

VueJS 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 VueJS 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>
Enter fullscreen mode Exit fullscreen mode

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

<MyAnchor href="/my-url">
  Go
</MyAnchor>
Enter fullscreen mode Exit fullscreen mode

There were a couple of gotchas:

Subscribe to get the latest posts right in your inbox (before anyone else).

Local vs global directive registration ๐ŸŒ

A global Vue directive can be defined like so:

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

It can also be defined locally as follows:

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

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

const nonAngularLinkDirective = {
  bind(el, binding) {},
  unbind(el) {}
};
Enter fullscreen mode Exit fullscreen mode

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

// non-angular-link-directive.js
export const nonAngularLinkDirective = {
  // directive definition
};
Enter fullscreen mode Exit fullscreen mode
// 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>
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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);
    });
  }
};
Enter fullscreen mode Exit fullscreen mode

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);
    });
  }
};
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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);
  }
};
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
    );
});
Enter fullscreen mode Exit fullscreen mode

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.

Subscribe to get the latest posts right in your inbox (before anyone else).

Cover photo by frank mckenna on Unsplash

Top comments (0)