.delegate()
.delegate( selector,eventType,handler ) Returns: jQuery
Description: Attach a handler to one or more events for all elements that match the selector, now or in the future, based on a specific set of root elements.
-
version added: 1.4.2.delegate( selector, eventType, handler )
selectorA selector to filter the elements that trigger the event.
eventTypeA string containing one or more space-separated JavaScript event types, such as "click" or "keydown," or custom event names.
handlerA function to execute at the time the event is triggered.
-
version added: 1.4.2.delegate( selector, eventType, eventData, handler )
selectorA selector to filter the elements that trigger the event.
eventTypeA string containing one or more space-separated JavaScript event types, such as "click" or "keydown," or custom event names.
eventDataA map of data that will be passed to the event handler.
handlerA function to execute at the time the event is triggered.
-
version added: 1.4.3.delegate( selector, events )
selectorA selector to filter the elements that trigger the event.
eventsA map of one or more event types and functions to execute for them.
Delegate is an alternative to using the .live() method, allowing for each binding of event delegation to specific DOM elements. For example the following delegate code:
$("table").delegate("td", "hover", function(){
$(this).toggleClass("hover");
});
Is equivalent to the following code written using .live():
$("table").each(function(){
$("td", this).live("hover", function(){
$(this).toggleClass("hover");
});
});
See also the .undelegate() method for a way of removing event handlers added in .delegate().
Passing and handling event data works the same way as it does for .bind().
Additional Notes:
- Since the
.live()method handles events once they have propagated to the top of the document, it is not possible to stop propagation of live events. Similarly, events handled by.delegate()will always propagate to the element to which they are delegated; event handlers on any elements below it will already have been executed by the time the delegated event handler is called.
Examples:
Example: Click a paragraph to add another. Note that .delegate() binds the click event to all paragraphs - even new ones.
<!DOCTYPE html>
<html>
<head>
<style>
p { background:yellow; font-weight:bold; cursor:pointer;
padding:5px; }
p.over { background: #ccc; }
span { color:red; }
</style>
<script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
<p>Click me!</p>
<span></span>
<script>
$("body").delegate("p", "click", function(){
$(this).after("<p>Another paragraph!</p>");
});
</script>
</body>
</html>Demo:
Example: To display each paragraph's text in an alert box whenever it is clicked:
$("body").delegate("p", "click", function(){
alert( $(this).text() );
});Example: To cancel a default action and prevent it from bubbling up, return false:
$("body").delegate("a", "click", function() { return false; })Example: To cancel only the default action by using the preventDefault method.
$("body").delegate("a", "click", function(event){
event.preventDefault();
});Example: Can bind custom events too.
<!DOCTYPE html>
<html>
<head>
<style>
p { color:red; }
span { color:blue; }
</style>
<script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
<p>Has an attached custom event.</p>
<button>Trigger custom event</button>
<span style="display:none;"></span>
<script>
$("body").delegate("p", "myCustomEvent", function(e, myName, myValue){
$(this).text("Hi there!");
$("span").stop().css("opacity", 1)
.text("myName = " + myName)
.fadeIn(30).fadeOut(1000);
});
$("button").click(function () {
$("p").trigger("myCustomEvent");
});
</script>
</body>
</html>