Aurelia Custom Elements & Custom Callback Events (tutorial)

Before Aurelia came onto the scene I had worked extensively with Angular and then shortly thereafter, React.js (sometimes both together). After using React for a while, I became accustomed to passing functions as callbacks to my components. So naturally when I started using Aurelia and creating custom elements, I tried the callback function approach first.

Callbacks are not the answer

While I was successful in creating a bindable property on my initial custom elements and then passing a function, it became apparent this approach is flawed. Not only do you have scope issues to deal with, but I encountered issues with singletons not being singletons and struggling to pass exact references.

In custom elements we can inject a reference to the custom element’s actual DOM element. What this allows us to do is manipulate the custom element itself and that includes firing custom events that can be listened too when used in your application.

This gives us the benefit of having callback like values, except we listen for events and fire a callback function, not expect the custom element to handle that for us internally.

An example

Recently I published a tutorial on creating a custom Select 2 custom styled select in Aurelia using custom elements. In this tutorial I use custom events to listen for changes on the custom styled select.

If you can’t be bothered wading through the tutorial, I am going to show how to trigger custom events on custom elements in Aurelia. This article from here onwards assumes you understand Aurelia enough to know what a custom element looks like and how Javascript native events sort of work.

I am also going to be using code by my tutorial, so ignore anything specific to jQuery or Select2. We are going to be mostly focusing on events themselves, events which have no 3rd party library dependencies.

The code

custom-element.js
This is the ViewModel for our custom element. This code is taken from my above linked tutorial, hence the references to jQuery and Select2.

// Aurelia Framework specific functionality
import {bindable, inject, customElement} from 'aurelia-framework';

// Import JSPM modules we installed earlier
import $ from 'jquery';
import 'select2';
import 'select2/css/select2.css!'

@customElement('select2') // Define the name of our custom element
@inject(Element) // Inject the instance of this element
export class CustomSelect {
    @bindable name = null; // The name of our custom select
    @bindable selected = false; // The default selected value
    @bindable options = {}; // The label/option values

    constructor(element) {
        this.element = element;
    }

    // Once the Custom Element has its DOM instantiated and ready for binding
    // to happenings within the DOM itself
    attached() {
        $(this.element).find('select')
            .select2()
            .on('change', (event) => {
                let changeEvent;

                if (window.CustomEvent) {
                    changeEvent = new CustomEvent('change', {
                        detail: {
                            value: event.target.value
                        },
                        bubbles: true
                    });
                } else {
                    changeEvent = document.createEvent('CustomEvent');
                    changeEvent.initCustomEvent('change', true, true, {
                        detail: {
                            value: event.target.value
                        }
                    });
                }
                this.element.dispatchEvent(changeEvent);
            });
    }
}

Now lets zero in on the part we are most interested in, the custom event logic.

    attached() {
        $(this.element).find('select')
            .select2()
            .on('change', (event) => {
                let changeEvent;

                if (window.CustomEvent) {
                    changeEvent = new CustomEvent('change', {
                        detail: {
                            value: event.target.value
                        },
                        bubbles: true
                    });
                } else {
                    changeEvent = document.createEvent('CustomEvent');
                    changeEvent.initCustomEvent('change', true, true, {
                        detail: {
                            value: event.target.value
                        }
                    });
                }
                this.element.dispatchEvent(changeEvent);
            });
    }

As you can see, we are creating a variable called changeEvent and then checking what the browser supports. Because CustomEvent is quite new and not supported that well in IE, we check for older support using document.createEvent()

The value of change we can see in the above code is the name of our custom event. For the sake of this example, we are going to keep the event name of “change”. The rest of the logic is pure native events API which you can read up on more here.

The important thing to note here is that setting the property bubbles to boolean of true will help prevent any issues you might encounter, particularly when using shadowDom in your custom elements.

Listening for events on custom elements

As you can see above our Select2 plugin fires off a jQuery change event, then inside we fire off a Javascript event called “change” with a property of “detail” and a sub-value of “value” which is on the event object itself accessible by: event.detail.value.

On our custom element we can subscribe to this event like this: <select2 change.delegate="myEventCallback($event)"></select2>

That’s it. It is that simple. Replace <select2></select2> with your custom element tagName and that’s it. Your custom elements can now fire custom events and you can bind to them on the custom element itself wherever you are using it.