Update 2016-11-28 The $dispatch and $broadcast methods have been deprecated in Vue 2.0, so if you've upgraded, be sure to read the migration guide that covers the changes.

Introduction

If, like myself, you find yourself new to the world of VueJS and not had much to do with Javascript in the past, aside from perhaps jQuery, having to change the way you think about working with a reactive JavaScript framework may be a bit overwhelming at first.

I recently found myself in a situation where I was repeating myself between components. This becomes unmaintainable very quickly, especially as your use of that code snippet finds its way into three or four or more components. Any time you make a change, you find yourself updating multiple locations.

Parent-Child communication in VueJS

Given a root Vue instance is accessible by all descendants via this.$root, a parent component can access child components via the this.$children array, and a child component can access it's parent via this.$parent, your first instinct might be to access these components directly.

The VueJS documentation warns against this specifically for two very good reasons:

  1. It tightly couples the parent to the child (and vice versa)
  2. You can't rely on the parent's state, given that it can be modified by a child component.

Not one to create more work for myself later, particularly when the documentation warns against it, I continued on to learn about Vue's custom event interface.

Vue's custom event interface

The event interface implemented by Vue allows you to communicate up and down the component tree. Leveraging the custom event interface gives you access to four methods:

  1. $on() - allows you to declare a listener on your Vue instance with which to listen to events
  2. $emit() - allows you to trigger events on the same instance (self)
  3. $dispatch() - send an event upward along the parent chain
  4. $broadcast() - send an event downward along the descendants chain

An example using pagination

The situation I found myself in that led to me learning about events was a simple paginator. Laravel provides this functionality out of the box when querying the database, so you only need to deal with the JSON response generated by the query.

Note that in this example, I'm using Laravel Elixir with Jeffrey Way's Vueify wrapper and Bootstrap's Pager component.

The Paginator component

// resources/assets/js/components/Paginator.vue
<template>
    <div id="paginator" v-show="previous || next">
        <nav>
            <ul class="pager">
                <li v-show="previous" class="previous">
                    <a @click.prevent="paginate('previous')" class="page-scroll" href="#">
                        < Previous
                    </a>
                </li>
                <li v-show="next" class="next">
                    <a @click.prevent="paginate('next')" class="page-scroll" href="#">
                        Next >
                    </a>
                </li>
            </ul>
        </nav>
    </div>
</template>

The template will only display if the pagination has a truth-y previous or next value. Likewise, the previous and next button will only be visible in the event the corresponding property is truth-y.

Next, we define the JavaScript that belongs to this component.

// resources/assets/js/components/Paginator.vue
<script>
    export default {

        data() {
            return {
                page: 1,
                next: false,
                previous: false
            }
        },

        methods: {
            paginate(direction) {
                if (direction === 'previous') {
                    --this.page;
                } else if (direction === 'next') {
                    ++this.page;
                }

                this.$dispatch('pageUpdated', this.page);
                this.$dispatch('paginationTriggered');
            },

            updatePagination(paginator) {
                this.next = paginator.next_page_url ? true : false;
                this.previous = paginator.prev_page_url ? true : false;
            }
        },

        events: {
            'responsePaginated': 'updatePagination'
        }

    };
</script>

What we've done now, is define some pretty basic methods, that we'll use to update the state of our paginator template, based on external events.

Whenever the paginate method is triggered, we'll increment or decrement the page being tracked in the instance and $dispatch an event. The first notifies the component tree that the page was updated, along with the new page value, as well as letting any component that's listening that pagination was triggered.

The component also has an events object, which maps an event name to a method (updatePagination) that should be executed when handling the event. Vue will automatically pass broadcast arguments to the receiving methods.

Note: I wasn't able to use an anonymous function in the events object. When doing so, Vue does not appear to pass along any variables. If you know more about this, let me know in the comments.

A parent component leveraging the Paginator

Next, I'll show you how to handle the two events we dispatched from the Paginator component, as well as how to broadcast the responsePaginated event down to the descendants.

// resources/assets/js/components/Parent.vue
<template>
    // Your paginated content will go here, perhaps in a table

    // Add the tag for the paginator component
    <paginator></paginator>
</template>

<script>
    import Paginator from './Paginator.vue';

    export default {

        components: { Paginator },

        data() {
            return {
                paginatedData: [],
                page: 1
            }
        },

        created() {
            this.fetchPaginatedData();
        },

        methods: {
            fetchPaginatedData() {
                this.$http.get('/api/paginated/data', { page: this.page }).then(
                    function (response) {
                        this.paginatedData = response.data.data;

                        this.$broadcast('responsePaginated', response.data);
                    }
                );
            },

            updatePage(page) {
                this.page = page;
            }
        },

        events: {
            'pageUpdated': 'updatePage',
            'paginationTriggered': 'fetchPaginatedData'
        }
}

Now that we extracted the pagination to its own component, the component responsible from loading paginated data from the Laravel backend is quite simple. We leverage vue-resource to make a GET request to the endpoint, update the instance data, and $broadcast the responsePaginated event with the response.data.

response.data contains an object with the current page number, previous and next page URLs, total results, and from and to values - that is to say the paginated result contains results 1 - 25 of 50, for example.

The broadcasted event makes its way down the descendant chain, where it will be processed by the paginator component's updatePagination method. This will reactively update the display of the list items, showing the next and previous links as necessary.

The main component also handles two events itself - the two events we fired with the $dispatch method in the paginator. The pageUpdated event fires the updatePage method, which simply sets the page property on the instance, which will be used as a query parameter in subsequent requests to the Laravel backend, whilst the paginationTriggered event will trigger the fetchPaginatedData method to fire another GET request to the Laravel backend.

Conclusion

This brings to a close my first attempt at handling communication between parent and child components within a Vue, with the aim at reducing duplication of code and separating of pagination concerns from the fetching component.

As a first pass, I'm quite happy with the results but eager to know if there is something I've missed or if there's other ways to tackle this in the future.

You'll note I only used Bootstrap's simple paginator with previous and next links. You could easily adjust this to render page links and pass the new page value along with the pageUpdated event.

One other thing that I did do in this instance, but have not shown in the sample code above is displaying the paginated counts and totals in the parent component. This is as straightforward as rendering the extra data from the GET request to the Laravel backend, along the following lines:

<template>
    <span v-show="! loading && pagination.total > 0">
        Showing results {{ pagination.from }} to {{ pagination.to }} of {{ pagination.total }}
    </span>

    // Rest of your view logic
</template>

<script>
    export default {

        data() {
            return {
                pagination: {
                    total: 0,
                    from: 0,
                    to: 0
                }
            }
        },

        methods: {
            fetchPaginatedData() {
                this.$http.get('/api/paginated/data', { page: this.page }).then(
                    function (response) {
                        pagination.total = response.data.total;
                        pagination.from = response.data.from;
                        pagination.to = response.data.to;

                        // Rest of your fetch logic
                    }
                );
            }
        }
    };
</script>

Update 5th March, 2016

Shortly after my original post, the VueJS Twitter account responded to my original tweet about it:

What is Vuex?

Vuex is an application architecture for centralized state management in Vue.js applications. It is inspired by Flux and Redux, but with simplified concepts and an implementation that is designed specifically to take advantage of Vue.js' reactivity system.

I've not looked into Vuex in great detail just yet, but it certainly looks like an interesting extension to VueJS if your application starts to reach the medium-to-large-scale SPA its documentation refers to. For the paginator example in this post, I don't believe it qualifies, but this is certainly something to keep in mind as your knowledge increases and your application grows.

Further Reading