Comprehensive event handling system with delegation support, namespaced events, and jQuery-compatible event management for modern browsers.
Add event listeners to elements with support for delegation, data passing, and multiple event types.
/**
* Add event listeners from an events object
* @param events - Object mapping event names to handler functions
* @returns The Cash collection for chaining
*/
on(events: Record<string, EventCallback>): this;
/**
* Add delegated event listeners from an events object
* @param events - Object mapping event names to handler functions
* @param selector - Selector for event delegation
* @returns The Cash collection for chaining
*/
on(events: Record<string, EventCallback>, selector: string): this;
/**
* Add event listeners with data from an events object
* @param events - Object mapping event names to handler functions
* @param data - Data to pass to event handlers
* @returns The Cash collection for chaining
*/
on(events: Record<string, EventCallback>, data: any): this;
/**
* Add event listeners with delegation and data from an events object
* @param events - Object mapping event names to handler functions
* @param selector - Selector for event delegation or null/undefined
* @param data - Data to pass to event handlers
* @returns The Cash collection for chaining
*/
on(events: Record<string, EventCallback>, selector: string | null | undefined, data: any): this;
/**
* Add a single event listener
* @param events - Space-separated event names
* @param callback - Event handler function
* @returns The Cash collection for chaining
*/
on(events: string, callback: EventCallback): this;
/**
* Add a delegated event listener
* @param events - Space-separated event names
* @param selector - Selector for event delegation
* @param callback - Event handler function
* @returns The Cash collection for chaining
*/
on(events: string, selector: string, callback: EventCallback): this;
/**
* Add an event listener with data
* @param events - Space-separated event names
* @param data - Data to pass to the event handler
* @param callback - Event handler function
* @returns The Cash collection for chaining
*/
on(events: string, data: any, callback: EventCallback): this;
/**
* Add an event listener with full options
* @param events - Space-separated event names
* @param selector - Selector for event delegation or null/undefined
* @param data - Data to pass to the event handler
* @param callback - Event handler function
* @param _one - Internal parameter for one-time events
* @returns The Cash collection for chaining
*/
on(events: string, selector: string | null | undefined, data: any, callback: EventCallback, _one?: boolean): this;Usage Examples:
// Basic event listeners
$('.button').on('click', function(event) {
console.log('Button clicked:', this);
});
// Multiple events
$('.input').on('focus blur', function(event) {
$(this).toggleClass('focused', event.type === 'focus');
});
// Event delegation
$('.container').on('click', '.dynamic-button', function(event) {
console.log('Dynamically added button clicked');
});
// Events with data
$('.item').on('click', { itemId: 123 }, function(event) {
console.log('Item ID:', event.data.itemId);
});
// Multiple events with object
$('.form').on({
submit: function(event) {
event.preventDefault();
console.log('Form submitted');
},
reset: function(event) {
console.log('Form reset');
}
});
// Namespaced events
$('.element').on('click.myPlugin', function() {
console.log('Namespaced click handler');
});
// Delegated events with data
$('.list').on('click', '.item', { action: 'select' }, function(event) {
console.log('Action:', event.data.action);
$(this).addClass('selected');
});
// Custom events
$('.component').on('customEvent', function(event, customData) {
console.log('Custom event data:', customData);
});Add event listeners that automatically remove themselves after being triggered once.
/**
* Add one-time event listeners from an events object
* @param events - Object mapping event names to handler functions
* @returns The Cash collection for chaining
*/
one(events: Record<string, EventCallback>): this;
/**
* Add one-time delegated event listeners from an events object
* @param events - Object mapping event names to handler functions
* @param selector - Selector for event delegation
* @returns The Cash collection for chaining
*/
one(events: Record<string, EventCallback>, selector: string): this;
/**
* Add one-time event listeners with data from an events object
* @param events - Object mapping event names to handler functions
* @param data - Data to pass to event handlers
* @returns The Cash collection for chaining
*/
one(events: Record<string, EventCallback>, data: any): this;
/**
* Add one-time event listeners with delegation and data from an events object
* @param events - Object mapping event names to handler functions
* @param selector - Selector for event delegation or null/undefined
* @param data - Data to pass to event handlers
* @returns The Cash collection for chaining
*/
one(events: Record<string, EventCallback>, selector: string | null | undefined, data: any): this;
/**
* Add a single one-time event listener
* @param events - Space-separated event names
* @param callback - Event handler function
* @returns The Cash collection for chaining
*/
one(events: string, callback: EventCallback): this;
/**
* Add a one-time delegated event listener
* @param events - Space-separated event names
* @param selector - Selector for event delegation
* @param callback - Event handler function
* @returns The Cash collection for chaining
*/
one(events: string, selector: string, callback: EventCallback): this;
/**
* Add a one-time event listener with data
* @param events - Space-separated event names
* @param data - Data to pass to the event handler
* @param callback - Event handler function
* @returns The Cash collection for chaining
*/
one(events: string, data: any, callback: EventCallback): this;
/**
* Add a one-time event listener with full options
* @param events - Space-separated event names
* @param selector - Selector for event delegation or null/undefined
* @param data - Data to pass to the event handler
* @param callback - Event handler function
* @returns The Cash collection for chaining
*/
one(events: string, selector: string | null | undefined, data: any, callback: EventCallback): this;Usage Examples:
// One-time click handler
$('.intro-popup').one('click', '.close', function() {
$(this).closest('.intro-popup').remove();
});
// One-time load event
$('.lazy-content').one('scroll', function() {
loadLazyContent();
});
// Multiple one-time events
$('.modal').one({
'modal:open': function() {
console.log('Modal opened for the first time');
},
'modal:close': function() {
console.log('Modal closed for the first time');
}
});Remove event listeners from elements with support for specific handlers, event types, and namespaces.
/**
* Remove all event listeners from elements
* @returns The Cash collection for chaining
*/
off(): this;
/**
* Remove event listeners for specific events
* @param events - Space-separated event names or namespaces
* @returns The Cash collection for chaining
*/
off(events: string): this;
/**
* Remove event listeners from an events object
* @param events - Object mapping event names to handler functions
* @returns The Cash collection for chaining
*/
off(events: Record<string, EventCallback>): this;
/**
* Remove a specific event listener
* @param events - Space-separated event names
* @param callback - Specific handler function to remove
* @returns The Cash collection for chaining
*/
off(events: string, callback: EventCallback): this;
/**
* Remove a specific delegated event listener
* @param events - Space-separated event names
* @param selector - Selector used for event delegation
* @param callback - Specific handler function to remove
* @returns The Cash collection for chaining
*/
off(events: string, selector: string, callback: EventCallback): this;Usage Examples:
// Remove all event listeners
$('.element').off();
// Remove specific event type
$('.button').off('click');
// Remove multiple event types
$('.input').off('focus blur');
// Remove namespaced events
$('.element').off('.myPlugin');
$('.element').off('click.myPlugin');
// Remove specific handler
function clickHandler() { console.log('clicked'); }
$('.button').on('click', clickHandler);
$('.button').off('click', clickHandler);
// Remove delegated events
$('.container').off('click', '.button');
// Remove events with object
const handlers = {
click: function() { console.log('click'); },
hover: function() { console.log('hover'); }
};
$('.element').on(handlers);
$('.element').off(handlers);Execute code when the DOM is fully loaded but before all resources are loaded.
/**
* Execute callback when DOM is ready
* @param callback - Function to execute when DOM is ready
* @returns The Cash collection for chaining
*/
ready(callback: Function): this;Usage Examples:
// DOM ready callback
$(document).ready(function() {
console.log('DOM is ready');
initializeApp();
});
// Shorthand syntax
$(function() {
console.log('DOM is ready');
});
// Multiple ready callbacks
$(document).ready(setupEventHandlers);
$(document).ready(loadInitialData);
$(document).ready(initializePlugins);Trigger events on elements with optional data passing.
/**
* Trigger an event on all elements
* @param event - Event name or Event object to trigger
* @param data - Optional data to pass to event handlers
* @returns The Cash collection for chaining
*/
trigger(event: Event | string, data?: any): this;Usage Examples:
// Trigger built-in events
$('.button').trigger('click');
$('.form').trigger('submit');
// Trigger custom events
$('.component').trigger('customEvent');
// Trigger events with data
$('.element').trigger('dataEvent', {
message: 'Hello',
timestamp: Date.now()
});
// Trigger with Event object
const customEvent = new Event('myEvent');
$('.element').trigger(customEvent);
// Trigger namespaced events
$('.element').trigger('click.myNamespace');
// Chain event triggering
$('.modal')
.trigger('modal:beforeOpen')
.addClass('open')
.trigger('modal:afterOpen');Event delegation allows you to attach event listeners to a parent element that will handle events for child elements, even if they're added dynamically:
// Handle clicks on current and future .button elements
$('.container').on('click', '.button', function() {
console.log('Button clicked:', this);
});
// Multiple levels of delegation
$('body').on('click', '.modal .close-button', function() {
$(this).closest('.modal').hide();
});Use namespaces to group related event handlers and remove them selectively:
// Add namespaced events
$('.element').on('click.plugin1', handler1);
$('.element').on('click.plugin2', handler2);
$('.element').on('hover.plugin1', handler3);
// Remove all events for plugin1
$('.element').off('.plugin1');
// Remove specific namespaced event
$('.element').off('click.plugin2');Pass data to event handlers that will be available in the event object:
$('.item').on('click', { itemId: 123, action: 'select' }, function(event) {
console.log('Item ID:', event.data.itemId);
console.log('Action:', event.data.action);
});Handle multiple event types with a single handler:
// Space-separated event names
$('.input').on('focus blur', function(event) {
$(this).toggleClass('focused', event.type === 'focus');
});
// Object syntax for different handlers
$('.element').on({
mouseenter: function() { $(this).addClass('hover'); },
mouseleave: function() { $(this).removeClass('hover'); },
click: function() { $(this).trigger('select'); }
});type EventCallback = {
(event: any, data?: any): any;
guid?: number;
};
interface Event {
namespace: string;
data: any;
// Plus standard Event properties
}