Vue.js Events Plugin

Simple global event bus for Vue.js applications with automatic subscription control. Zero dependencies.

• Installation
• Setup
  • Bundler
  • Browser
• Usage
  • Listening to Events
  • Emitting Events
• API ($events)
• License

Installation

npm install --save vue-plugin-events

Setup

Bundler (Webpack, Rollup)

import Vue from 'vue'
import VueEvents from 'vue-plugin-events'

Vue.use(VueEvents)

Browser

<!-- Include after Vue -->
<!-- Local files -->
<script src="vue-plugin-events/dist/vue-plugin-events.umd.js"></script>

<!-- From CDN -->
<script src="https://cdn.jsdelivr.net/npm/vue-plugin-events"></script>

Usage

Listening to Events

The plugin will automatically subscribe a component to events defined within its body. This is achieved using a new section named events. When your component is destroyed, so are any listeners that have been automatically created.

The handlers follow a pattern similar to component watch section.

// MyComponent.vue
export default {
  data: () => ({
    myValue: 'anything'
  }),
  methods: {
    doSomething (arg) { /*...*/ }
  },
  events: {

    // will execute method `doSomething` when event named `someEvent` is emitted
    someEvent: 'doSomething',

    // will fire when event named `someHandledEvent` is emitted
    someHandledEvent (v) {
      this.doSomething(v)
    },

    // will fire when event named `immediateEvent` is emitted, and as
    // soon as the component is loaded and this section is evaluated,
    // much like `immediate` option from watchers
    immediateEvent: {
      immediate: true,
      handler (v) {
        this.doSomething(v)
      }
    },

    // will fire when a `justOnceEvent` is fired, and then won't fire again;
    // may fire twice if combined with `immediate`
    justOnceEvent: {
      once: true,
      handler (v) {
        console.log('arg is', v)
      }
    }

  }
}

Emitting Events

Every component will be inject with an instance of $event, which allows the developer to emit events into the application-wide event bus. Any components listening to the emitted event will be triggered. More details can be seen in the API section below.

The methods exposed by $event below are basically the same as normal event methods in a Vue component, but instead of having only the parent component as a listeners, any component can subscribe to any events.

// AnyComponent.vue
export default {
  // ...
  methods: {
    onSomething () {
      this.$events.emit('someEvent', this.payload)
    }
  },
  // ...
}

API ($events)

.emit

• Arguments
  • {string} eventName
  • [...args]
• Usage
  • Triggers an event on the event bus. Any additional arguments will be passed into the listener’s callback function.

.on

• Arguments
  • {string | Array<string>} event (array only supported in Vue 2.2.0+)
  • {Function} callback
• Usage
  • Listens for an event in the global event bus. Normally, it is easier to allow the plugin to control the subscription of events. However, special cases do exist, so you can manually listen for an event if need be; just keep in mind that the plugin does not track manual subscriptions, so you must remember to unsubscribe before the component is destroyed. The callback will receive all the additional arguments passed into the event-triggering method.

.once

• Arguments
  • {string | Array<string>} event (array only supported in Vue 2.2.0+)
  • {Function} callback
• Usage
  • Listens for an event in the global event bus, but only once. The listener will be removed once it triggers for the first time.

.off

• Arguments
  • {string | Array<string>} event (array only supported in Vue 2.2.2+)
  • {Function} [callback]
• Usage
  • Removes a global event bus listener. Both event and callback are necessary, to avoid removing more listeners than intended.

License

ISC © 2019 Ricardo Nolde