.triggerHandler() JQ Home  <<  Events  <<  .triggerHandler()

Event handler.

Description

The .triggerHandler() method is used to manually fire all event handlers on an element, for the specified event type(s), optionally passing parameters.

  • The .triggerHandler() method is similar to the .trigger() method, with the following exceptions:
    1. Whilst the .trigger() method operates on all elements matched by the jQuery object, the .triggerHandler() method only operates on the first matched element.
    2. Events that are created using the .triggerHandler() method do not bubble up the DOM hierarchy and if not handled by the target element directly, do nothing.
    3. The .triggerHandler() method does not cause the default behavior of an event to occur (such as a form submission).
    4. The .triggerHandler() method returns whatever value was returned by the last handler it caused to be executed, so no chaining is possible. If no handlers are triggered, the .triggerHandler() method returns undefined.

Syntax

Signature Description
.triggerHandler( eventType [, extraParameters] )Manually fire all event handlers on an element, for the specified event type, optionally passing parameters.
.triggerHandler( event [, extraParameters] )Manually fire all event handlers on an element, for the specified event, optionally passing parameters.

Parameters

Parameter Description Type
eventTypeA string containing one or more DOM event types or custom event names.
  • If the string used for eventType is not the name of a native DOM event, the handler is bound to a custom event. Custom events are never called by the browser, but can be handled manually from other JavaScript code using the .trigger()) or .triggerHandlerHandler() methods.
  • If a period (.) character is present anywhere in the eventType string, then that event becomes namespaced. The characters before the period (.) character represent the eventType, whilst the characters after the period (.) character represent the namespace. As an example .triggerHandler( 'anEventType.aNamespace', handler) could be used to handle some events whilst not affecting events for .triggerHandler( 'anEventType.aNamespace2', handler). In essence, namespacing allows us to action certain events for an eventType without affecting other events for that eventType.
String
extraParametersAdditional parameters to be passed to the event handler.
  • The event object is always passed as the first parameter to an event handler, but if additional parameters are specified during a .triggerHandler() call, these parameters will be passed to the handler as well. A single parameter can be passed as is; for more than one parameter, pass the parameters enclosed in square brackets like an array, or pass an array.
 Array or
PlainObject
eventA jQuery.event object.Event

Return

Object returned from last handler or undefined.

.triggerHandler( eventType [, extraParameters] ) Example  Events  <<  Top

Manually fire all event handlers on an element, for the specified event type, optionally passing parameters.

In the example below when you enter or leave the 'div3' element the mouseenter and mouseleave JavaScript events fire.

When we press the left button we triggerHandler the mouseenter JavaScript event manually. We are not passing across a parameter for any events so the output contains 'undefined' for the param parameter.

When we press the right button we triggerHandler the mouseenter JavaScript event manually. We are passing across the string '**PASSED PARAM**' for the param parameter, so the output message will contain this when fired from the triggerHandler or 'undefined' otherwise.


$(function(){
  $('#div3').on({
     'mouseenter.ns3': function(event, param) {
       $(this).css({backgroundColor: 'teal', color: 'black'})
              .append('**entering "div3". Passed param : ' + param + '<br>');
     },

     'mouseleave.ns3': function() {
       $(this).css({backgroundColor: 'maroon', color: 'white'})
              .append('**leaving "div3"  ' + '<br>');
     }
  });

  $('#btn4').on('click', function(){
     $('#div3').triggerHandler('mouseenter.ns3');
  });

  $('#btn5').on('click', function(){
     $('#div3').triggerHandler('mouseenter.ns3', '**PASSED PARAM**');
  });
});

div3. Some initial text.

Press the button below to action the above code:

             

.triggerHandler( event [, extraParameters] ) Example  Events  <<  Top

Manually fire all event handlers on an element, for the specified event type, optionally passing parameters.

In the example below when you enter or leave the 'div3' element the mouseenter and mouseleave JavaScript events fire.

When we press the left button we triggerHandler the mouseenter JavaScript event manually. We are not passing across a parameter for any events so the output contains 'undefined' for the param parameter.

When we press the right button we triggerHandler the mouseenter JavaScript event manually. We are passing across the string '**PASSED PARAM**' for the param parameter, so the output message will contain this when fired from the triggerHandler or 'undefined' otherwise.


$(function(){
  $('#div8').on({
     'mouseenter.ns8': function(event, param) {
       $(this).css({backgroundColor: 'teal', color: 'black'})
              .append('**entering "div8". Passed param : ' + param + '<br>');
     },

     'mouseleave.ns8': function() {
       $(this).css({backgroundColor: 'maroon', color: 'white'})
              .append('**leaving "div8"  ' + '<br>');
     }
  });

  $('#btn11').on('click', function(){
     var ourEvent = $.Event('mouseenter.ns8');
     $('#div8').triggerHandler(ourEvent);
  });
  
  $('#btn12').on('click', function(){
     var ourEvent = $.Event('mouseenter.ns8');
     ourEvent.param = "**PASSED PARAM**";
     $('#div8').triggerHandler(ourEvent, ourEvent.param);
  });
});

div8. Some initial text.

Press the button below to action the above code:

             

Related Tutorials

jQuery Advanced Tutorials - Lesson 4 - Event Handler Attachments