Lucid.js / Events

Introduction 🔗

Lucid supports two kinds of events:

DOM events, such as click, mouseover etc
Lifecycle events, such as when a route is changed

We'll look at each of these in turn.

DOM events 🔗

Lucid allows you to listen for DOM events in your components. There are two ways to do this.

Inline events 🔗

Inline events means putting event attributes on the elements in your components, like so:

<button onclick=foo>Click me</button>

When the button is clicked, it will look for and call a method, foo(), registered on the component's events object.

this.events.foo = () => alert('You clicked me!');

Centralised events 🔗

The advantage of inline events is that you can see at a glance in your HTML which events are registered. The drawback is a separate event is registered for each element they're applied to, and this can be a bad idea for lots of elements.

Instead, there's nothing stopping you using traditional, centralised event handling from your component's JavaScript. This also means you can take advantage of event delegation patterns.

//listen for clicks to our many, many buttons
this.DOM.addEventListener('click', evt => {
    if (!evt.target.matches('button')) return;
    alert('You clicked a button');
});

Running expressions 🔗

Rather than call callbacks as shown above, you can also run JavaScript expressions in-situ. These expressions run in the context of the component, so you can reference the component's data.

<div>
    <button onclick='this.data.counter++'>Increment counter</button>
    <h1>Counter is: {{counter}}</h1>
</div>
<script>
this.data.counter = 0;
</script>

Passing arguments 🔗

It's possible to pass arguments from inline events to the registered callbacks. Suppose the following component:

<div>
    <button onclick='foo(1)'>Click me</button>
    <button onclick='foo(2)'>Click me</button>
</div>
<script>
this.events.foo = which => alert('You clicked button '+which+'!');
</script>

There, we're passing static values. But this pattern can be extremely useful when using repeaters. We can pass along repeater data to the event callback:

<div>
    <button onclick='colourChoice("{{$value}}")'>{{$value}}</button>
</div>
<script>
this.events.colourChoice = choice => alert('You chose '+choice);
this.repeaters = {
    button: ['Yellow', 'Green', 'Red', 'Blue']
};
</script>

Lifecycle events 🔗

Lucid supports a handful of lifecycle events that concern when things happen internally. Components can subscribe to these events. They are:

rendered -fires when a component has rendered (template parsed and output, JavaScript run) but before any child/descendant components have themselves been rendered.
fullyRendered - fires when a component and its child/descendant components have rendered.
routeChanged - fires when the app's route changes. See Routes.
message - fires when the component receives a message from another component (see Component messaging.)
mutated - fires when a component's data is changed. The callback is automatically forwarded a) the parent object of the property that was changed (either the component's data object or a sub-object within it) and b) the name of the property that was changed.

Events are registered via the on() method of the component API, which expects two params: