jQuery.proxy()

Categories: Deprecated > Deprecated 3.3 | Events > Event Handler Attachment | Utilities

jQuery.proxy( function, context )Returns: Functionversion deprecated: 3.3

Description: Takes a function and returns a new one that will always have a particular context.

Note: This API has been deprecated in jQuery 3.3; please use the native Function.prototype.bind method instead.

This method is most useful for attaching event handlers to an element where the context is pointing back to a different object. Additionally, jQuery makes sure that even if you bind the function returned from jQuery.proxy() it will still unbind the correct function if passed the original.

Be aware, however, that jQuery's event binding subsystem assigns a unique id to each event handling function in order to track it when it is used to specify the function to be unbound. The function represented by jQuery.proxy() is seen as a single function by the event subsystem, even when it is used to bind different contexts. To avoid unbinding the wrong handler, use a unique event namespace for binding and unbinding (e.g., "click.myproxy1") rather than specifying the proxied function during unbinding.

As of jQuery 1.6, any number of additional arguments may be supplied to $.proxy(), and they will be passed to the function whose context will be changed.

As of jQuery 1.9, when the context is null or undefined the proxied function will be called with the same this object as the proxy was called with. This allows $.proxy() to be used to partially apply the arguments of a function without changing the context.

Examples:

Change the context of functions bound to a click handler using the "function, context" signature. Unbind the first handler after first click.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>jQuery.proxy demo</title>
  <script src="https://code.jquery.com/jquery-3.7.1.js"></script>
</head>
<body>
 
<p><button type="button" id="test">Test</button></p>
<div id="log"></div>
 
<script>
var me = {
  type: "zombie",
  test: function( event ) {
    // Without proxy, `this` would refer to the event target
    // use event.target to reference that element.
    var element = event.target;
    $( element ).css( "background-color", "red" );
 
    // With proxy, `this` refers to the me object encapsulating
    // this function.
    $( "#log" ).append( "Hello " + this.type + "<br>" );
    $( "#test" ).off( "click", this.test );
  }
};
 
var you = {
  type: "person",
  test: function( event ) {
    $( "#log" ).append( this.type + " " );
  }
};
 
// Execute you.test() in the context of the `you` object
// no matter where it is called
// i.e. the `this` keyword will refer to `you`
var youClick = $.proxy( you.test, you );
 
// attach click handlers to #test
$( "#test" )
  // this === "zombie"; handler unbound after first click
  .on( "click", $.proxy( me.test, me ) )
 
  // this === "person"
  .on( "click", youClick )
 
  // this === "zombie"
  .on( "click", $.proxy( you.test, me ) )
 
  // this === "<button> element"
  .on( "click", you.test );
</script>
 
</body>
</html>

Demo:

Enforce the context of the function using the "context, function name" signature. Unbind the handler after first click.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>jQuery.proxy demo</title>
  <script src="https://code.jquery.com/jquery-3.7.1.js"></script>
</head>
<body>
 
  <p><button id="test">Test</button></p>
  <p id="log"></p>
 
<script>
var obj = {
  name: "John",
  test: function() {
    $( "#log" ).append( this.name );
    $( "#test" ).off( "click", obj.test );
  }
};
$( "#test" ).on( "click", jQuery.proxy( obj, "test" ) );
</script>
 
</body>
</html>

Demo:

Change the context of a function bound to the click handler,

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>jQuery.proxy demo</title>
  <script src="https://code.jquery.com/jquery-3.7.1.js"></script>
</head>
<body>
 
<p><button type="button" id="test">Test</button></p>
<div id="log"></div>
 
<script>
var me = {
  // I'm a dog
  type: "dog",
 
  // Note that event comes *after* one and two
  test: function( one, two, event ) {
    $( "#log" )
 
      // `one` maps to `you`, the 1st additional
      // argument in the $.proxy function call
      .append( "<h3>Hello " + one.type + ":</h3>" )
 
      // The `this` keyword refers to `me`
      // (the 2nd, context, argument of $.proxy)
      .append( "I am a " + this.type + ", " )
 
      // `two` maps to `they`, the 2nd additional
      // argument in the $.proxy function call
      .append( "and they are " + two.type + ".<br>" )
 
      // The event type is "click"
      .append( "Thanks for " + event.type + "ing." )
 
      // The clicked element is `event.target`,
      // and its type is "button"
      .append( "the " + event.target.type + "." );
  }
};
 
var you = { type: "cat" };
var they = { type: "fish" };
 
// Set up handler to execute me.test() in the context
// of `me`, with `you` and `they` as additional arguments
var proxy = $.proxy( me.test, me, you, they );
 
$( "#test" )
  .on( "click", proxy );
</script>
 
</body>
</html>

Demo: