Skip to content

Commit 2c02411

Browse files
kswedbergkswedberg
committed
Update $.proxy to show signatures w/ additional args
* Refers to jquery#80. Not closing until reviewed. * Note: Use of "slash-star" comments is necessary because of the way we convert code in html to demos.
1 parent 28a2302 commit 2c02411

File tree

1 file changed

+100
-19
lines changed

1 file changed

+100
-19
lines changed

‎entries/jQuery.proxy.xml

Lines changed: 100 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,37 @@
1919
<desc>The name of the function whose context will be changed (should be a property of the <code>context</code> object).</desc>
2020
</argument>
2121
</signature>
22+
<signature>
23+
<added>1.6</added>
24+
<argument name="function" type="Function">
25+
<desc>The function whose context will be changed.</desc>
26+
</argument>
27+
<argument name="context" type="PlainObject">
28+
<desc>The object to which the context (<code>this</code>) of the function should be set.</desc>
29+
</argument>
30+
<argument name="additionalArguments" type="Anything" optional="true">
31+
<desc>Any number of arguments to be passed to the function referenced in the <code>function</code> argument.</desc>
32+
</argument>
33+
</signature>
34+
<signature>
35+
<added>1.6</added>
36+
<argument name="context" type="PlainObject">
37+
<desc>The object to which the context of the function should be set.</desc>
38+
</argument>
39+
<argument name="name" type="String">
40+
<desc>The name of the function whose context will be changed (should be a property of the <code>context</code> object).</desc>
41+
</argument>
42+
<argument name="additionalArguments" type="Anything" optional="true">
43+
<desc>Any number of arguments to be passed to the function named in the <code>name</code> argument.</desc>
44+
</argument>
45+
</signature>
46+
2247
<desc>Takes a function and returns a new one that will always have a particular context.</desc>
2348
<longdesc>
2449
<p>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 <code>jQuery.proxy()</code> it will still unbind the correct function if passed the original.</p>
2550
<p>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 <code>jQuery.proxy()</code> 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., <code>"click.myproxy1"</code>) rather than specifying the proxied function during unbinding.
2651
</p>
52+
<p><strong>As of jQuery 1.6</strong>, any number of additional arguments may supplied to <code>$.proxy()</code>, and they will be passed to the function whose context will be changed.</p>
2753
</longdesc>
2854
<example>
2955
<desc>Change the context of functions bound to a click handler using the "function, context" signature. Unbind the first handler after first click.</desc>
@@ -35,13 +61,13 @@
3561
var me = {
3662
type: "zombie",
3763
test: function(event) {
38-
// Without proxy, `this` would refer to the event target
39-
// use event.target to reference that element.
64+
/* Without proxy, `this` would refer to the event target */
65+
/* use event.target to reference that element. */
4066
var element = event.target;
4167
$(element).css("background-color", "red");
4268
43-
// With proxy, `this` refers to the me object encapsulating
44-
// this function.
69+
/* With proxy, `this` refers to the me object encapsulating */
70+
/* this function. */
4571
$("#log").append( "Hello " + this.type + "<br>" );
4672
$("#test").unbind("click", this.test);
4773
}
@@ -54,22 +80,26 @@ var you = {
5480
}
5581
};
5682
57-
// execute you.test() in the context of the `you` object
58-
// no matter where it is called
59-
// i.e. the `this` keyword will refer to `you`
83+
/* execute you.test() in the context of the `you` object */
84+
/* no matter where it is called */
85+
/* i.e. the `this` keyword will refer to `you` */
6086
var youClick = $.proxy( you.test, you );
6187
6288
63-
// attach click handlers to #test
89+
/* attach click handlers to #test */
6490
$("#test")
65-
// this === "zombie"; handler unbound after first click
66-
.click( $.proxy( me.test, me ) )
67-
// this === "person"
68-
.click( youClick )
69-
// this === "zombie"
70-
.click( $.proxy( you.test, me ) )
71-
// this === "<button> element"
72-
.click( you.test );
91+
92+
/* this === "zombie"; handler unbound after first click */
93+
.on( "click", $.proxy( me.test, me ) )
94+
95+
/* this === "person" */
96+
.on( "click", youClick )
97+
98+
/* this === "zombie" */
99+
.on( "click", $.proxy( you.test, me ) )
100+
101+
/* this === "<button> element" */
102+
.on( "click", you.test );
73103
]]></code>
74104
</example>
75105
<example>
@@ -83,14 +113,65 @@ $("#test")
83113
name: "John",
84114
test: function() {
85115
$("#log").append( this.name );
86-
$("#test").unbind("click", obj.test);
116+
$("#test").off("click", obj.test);
87117
}
88118
};
89119
90-
$("#test").click( jQuery.proxy( obj, "test" ) );
120+
$("#test").on( "click", jQuery.proxy( obj, "test" ) );
91121
]]></code>
92122
</example>
123+
124+
<example>
125+
<desc>Change the context of a function bound to the click handler,
126+
</desc>
127+
<html><![CDATA[
128+
<p><button type="button" id="test">Test</button></p>
129+
<div id="log"></div>
130+
]]></html>
131+
<code><![CDATA[
132+
var me = {
133+
/* I'm a dog */
134+
type: "dog",
135+
136+
/* Note that event comes *after* one and two */
137+
test: function(one, two, event) {
138+
$("#log")
139+
140+
/* `one` maps to `you`, the 1st additional */
141+
/* argument in the $.proxy function call */
142+
.append( "<h3>Hello " + one.type + ":</h3>" )
143+
144+
/* the `this` keyword refers to `me` */
145+
/*(the 2nd, context, argument of $.proxy) */
146+
.append( "I am a " + this.type + ", " )
147+
148+
/* `two` maps to `they`, the 2nd additional */
149+
/* argument in the $.proxy function call */
150+
.append( "and they are " + two.type + ".<br>" )
151+
152+
/* the event type is "click" */
153+
.append( "Thanks for " + event.type + "ing " )
154+
155+
/* the clicked element is `event.target`, */
156+
/* and its type is "button" */
157+
.append( "the " + event.target.type + "." );
158+
}
159+
};
160+
161+
var you = { type: "cat" };
162+
var they = { type: "fish" };
163+
164+
165+
/* Set up handler to execute me.test() in the context */
166+
/* of `me`, with `you` and `they` as additional arguments */
167+
var proxy = $.proxy( me.test, me, you, they );
168+
169+
$("#test")
170+
.on( "click", proxy );
171+
]]></code>
172+
</example>
93173
<category slug="events/event-handler-attachment"/>
94174
<category slug="utilities"/>
95175
<category slug="version/1.4"/>
96-
</entry>
176+
<category slug="version/1.6"/>
177+
</entry>

0 commit comments

Comments
 (0)