YumJS Events Documentation

Events

Documention for YumJS's event methods.

  • _createEvent
  • removeEvent (off)
  • addEvent (on)
  • trigger

Creating Events

You can create custom events with _createEvent().

Notice how _createEvent starts with an underscore. This means that when used it returns the event and therefore is not chainable. The reason for this is so that you can assign the event to a variable.

// create a custom event and assign it to a variable

  const myEvt = yum()._createEvent('myEvt');

// * optional
// set optional 2nd param true to bubble, 3rd param true to set cancelable.
// The deafult for both is false.

Now that you have an event, you can listen for it by adding listeners to DOM elements.


// Use addEvent to add a listener for the the custom event on .button class

yum('.button').addEvent( 'myEvt', function(e) { console.log('I am myEvt'), true});

Trigger Events

Now that you have something listening for the event myEvt you created above, you can use normal javascript dispatchEvent or Yum's trigger method.

Granted this is a silly example using a click event to trigger another event but lets keep things simple for now.


// First we need to be able to click the button.
// We will use this runme function for a click handler.

const runme = function(e) {
e.target.textContent = 'waiting for event';

// Inside the handler for button, trigger the myEvt event after a timeout.

setTimeout(t => {
yum('.button').trigger('myEvt');
}, 2000);
};


// Use addEvent to add the click handler to the button

yum('.button').addEvent('click', runme); 

// * optional
// optional 3rd parameter to addEvent is capture that defaults to false
// can be a dictionary like {"capture": true}.

yum('.button').addEvent('click', runme, {"capture": true} ); 

// default that translates to {"capture": false}

yum('.button').addEvent('click', runme); 

Try it

Click the button and wait 2 seconds for the tiggered event myEvt to activate.

Button


addEvent() and on()

In the example above we used addEvent. You can probably see how it works but let's go over it more detail.

addEvent takes the same parameters as JavaScript's addEventListener but with two improvements.

1 The first parameter to addEvent can be a comma delimited list of event names. A new listener will be made for each event name in the list.

2 Combined with the above it's less characters to type and can be used with the Yum alias on() which makes it even shorter. The on() alias for addEvent takes the same parameters.

// on is an alias  for addEvent
// assumes runme function exists

yum('.button').addEvent('mousedown, touchstart', runme);

//same as above but with on alias

yum('.button').on('mousedown, touchstart', runme);

Use Named Functions for Handlers

If you plan on removing event listeners from elements it is important to send in the function names of the handlers as parameters to on() and addevent(). Doing so will allow you to properly remove the event.


removeEvent() and off()

Removing the event with removeEvent() and it's alias off() takes the same parameters you gave when you created the listeners with addEvent() and on().

// off is an alias for removeEvent
// assumes runme function exists

yum('.button').removeEvent('mousedown, touchstart', runme);

//same as above but with off alias

yum('.button').off('mousedown, touchstart', runme);

To reiterate, addEvent() and on() should be removed with the same options they were initialized with using removeEvent() or off() with the options being the same as addEventListener.

See MDN removeEventListener.


Summary

Now you should understand how to create custom events with _createEvent() and listen for events with addEvent() and on() (listen for any event not just events created with _createEvent()). You should also know how to stop listening for events using removeEvent() or off() and how to trigger events using Yum's trigger() method.

If you have any questions about Yum please contact me.