.trigger()S2C Home « Events « .trigger()

Event handler trigger.

Description

The .trigger() method is used to manually fire all event handlers and behaviours on the matched set, for the specified event type.

  • Any event handlers attached with the .bind() method or one of its shortcut methods, or the .on() method are triggered when the corresponding event occurs. The handlers can be fired manually with the .trigger() method and the handlers are executed in the same order as if the event were triggered normally by the user.
  • Events that are triggered using the .trigger() method bubble up the DOM tree and if required can be stopped from bubbling in two ways:
    1. An event handler can stop bubbling occurring by returning false from the handler
    2. Calling the .stopPropagation() method on the Event object passed into the event.
  • When an event reaches an element, all handlers bound to that event type for the element are fired. If multiple handlers are registered for the element, they will always execute in the order in which they were bound. When all handlers have finished executing, the event continues along the normal event propagation path.
  • The .trigger() method can also be used on jQuery collections that wrap plain JavaScript objects, akin to the observer pattern. When the event is triggered, any event handlers attached to the object are called.

Syntax

Signature Description
.trigger( eventType [, extraParameters] )Manually fire all event handlers and behaviours on the matched set, for the specified event, optionally passing parameters.
.trigger( events )Manually fire a specified map of event type(s) and functions to execute for them.

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 triggered manually from other JavaScript code using the .trigger()) or .triggerHandler() 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 .trigger('anEventType.aNamespace', handler) could be used to handle some events whilst not affecting events for .trigger('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 .trigger() 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

A jQuery object.

.trigger( eventType [, extraParameters] ) ExampleTop

Manually fire all event handlers and behaviours on the matched set, for the specified event, optionally passing parameters.

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

When we press the left button we trigger 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 trigger 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 trigger or 'undefined' otherwise.


$(function(){
  $('#div1').on({
     'mouseenter.ns1': function(event, param) {
       $(this).css({backgroundColor: 'orange', color: 'black'})
              .append('**entering "div1". Passed param : ' + param);
     },
     'mouseleave.ns1': function() {
       $(this).css({backgroundColor: 'green', color: 'white'})
              .append('**leaving "div1"  ');
     }
  });
  $('#btn1').on('click', function(){
     $('#div1').trigger('mouseenter.ns1');
  });
  $('#btn2').on('click', function(){
     $('#div1').trigger('mouseenter.ns1', '**PASSED PARAM**');
  });
});

div1. Some initial text.



Press the button below to action the above code:

             

.trigger( events ) ExampleTop

Manually fire a jQuery.event object on the matched set.

In the example below when you enter or leave the 'div2' element the mouseenter and mouseleave JavaScript events fire. The parameter passed is undefined as this is only triggered from the button click.

When we press the button we manually create a custom jQuery.event object (ourEvent). this is equivalent to typing  {type:'mouseenter.ns2',param:'passed param'}; within the call to the .trigger() method but in a cleaner way. The type property indicates the kind of event being raised. We then trigger the mouseenter JavaScript event on 'div2' passing across our custom event object. Now we see our passed parameter value of 'passed param' instead of 'undefined'.


$(function(){
  $('#div2').on({
     'mouseenter.ns2': function(ourEvent) {
       $(this).css({backgroundColor: 'yellow', color: 'black'})
              .append('**entering "div2". Event param : ' + ourEvent.param);
     },
     'mouseleave.ns2': function() {
       $(this).css({backgroundColor: 'red', color: 'white'})
              .append('**leaving "div2"  ');
     }
  });
  $('#btn3').on('click', function(){
     var ourEvent = $.Event('mouseenter.ns2');
     ourEvent.param = 'passed param';
     $('#div2').trigger(ourEvent);
  });
});

div2. Some initial text.



Press the button below to action the above code: