control-freak-ide/Control-Freak-Documentation/jQuery/docs/entries/jQuery.proxy.json

{"name":"jQuery.proxy","type":"method","title":"jQuery.proxy()","deprecated":null,"removed":null,"desc":"Takes a function and returns a new one that will always have a particular context.","categories":["events/event-handler-attachment","utilities","version/1.4","version/1.6"],"entries":[{"return":"Function","signatures":[{"added":"1.4","argument":[{"desc":"The function whose context will be changed.","name":"function","type":"Function"},{"desc":"The object to which the context (<code>this</code>) of the function should be set.","name":"context","type":"PlainObject"}]},{"added":"1.4","argument":[{"desc":"The object to which the context of the function should be set.","name":"context","type":"PlainObject"},{"desc":"The name of the function whose context will be changed (should be a property of the <code>context</code> object).","name":"name","type":"String"}]},{"added":"1.6","argument":[{"desc":"The function whose context will be changed.","name":"function","type":"Function"},{"desc":"The object to which the context (<code>this</code>) of the function should be set.","name":"context","type":"PlainObject"},{"desc":"Any number of arguments to be passed to the function referenced in the <code>function</code> argument.","name":"additionalArguments","type":"Anything","optional":"true"}]},{"added":"1.6","argument":[{"desc":"The object to which the context of the function should be set.","name":"context","type":"PlainObject"},{"desc":"The name of the function whose context will be changed (should be a property of the <code>context</code> object).","name":"name","type":"String"},{"desc":"Any number of arguments to be passed to the function named in the <code>name</code> argument.","name":"additionalArguments","type":"Anything","optional":"true"}]}],"examples":[{"desc":"Change the context of functions bound to a click handler using the \"function, context\" signature. Unbind the first handler after first click.","html":"\n<p><button type=\"button\" id=\"test\">Test</button></p>\n<div id=\"log\"></div>\n","code":"\nvar me = {\n  type: \"zombie\",\n  test: function( event ) {\n    // Without proxy, `this` would refer to the event target\n    // use event.target to reference that element.\n    var element = event.target;\n    $( element ).css( \"background-color\", \"red\" );\n\n    // With proxy, `this` refers to the me object encapsulating\n    // this function.\n    $( \"#log\" ).append( \"Hello \" + this.type + \"<br>\" );\n    $( \"#test\" ).off( \"click\", this.test );\n  }\n};\n\nvar you = {\n  type: \"person\",\n  test: function( event ) {\n    $( \"#log\" ).append( this.type + \" \" );\n  }\n};\n\n// Execute you.test() in the context of the `you` object\n// no matter where it is called\n// i.e. the `this` keyword will refer to `you`\nvar youClick = $.proxy( you.test, you );\n\n// attach click handlers to #test\n$( \"#test\" )\n  // this === \"zombie\"; handler unbound after first click\n  .on( \"click\", $.proxy( me.test, me ) )\n\n  // this === \"person\"\n  .on( \"click\", youClick )\n\n  // this === \"zombie\"\n  .on( \"click\", $.proxy( you.test, me ) )\n\n  // this === \"<button> element\"\n  .on( \"click\", you.test );\n"},{"desc":"Enforce the context of the function using the \"context, function name\" signature. Unbind the handler after first click.","html":"\n  <p><button id=\"test\">Test</button></p>\n  <p id=\"log\"></p>\n","code":"\nvar obj = {\n  name: \"John\",\n  test: function() {\n    $( \"#log\" ).append( this.name );\n    $( \"#test\" ).off( \"click\", obj.test );\n  }\n};\n$( \"#test\" ).on( \"click\", jQuery.proxy( obj, \"test\" ) );\n"},{"desc":"Change the context of a function bound to the click handler,\n    ","html":"\n<p><button type=\"button\" id=\"test\">Test</button></p>\n<div id=\"log\"></div>\n","code":"\nvar me = {\n  // I'm a dog\n  type: \"dog\",\n\n  // Note that event comes *after* one and two\n  test: function( one, two, event ) {\n    $( \"#log\" )\n\n      // `one` maps to `you`, the 1st additional\n      // argument in the $.proxy function call\n      .append( \"<h3>Hello \" + one.type + \":</h3>\" )\n\n      // The `this` keyword refers to `me`\n      // (the 2nd, context, argument of $.proxy)\n      .append( \"I am a \" + this.type + \", \" )\n\n      // `two` maps to `they`, the 2nd additional\n      // argument in the $.proxy function call\n      .append( \"and they are \" + two.type + \".<br>\" )\n\n      // The event type is \"click\"\n      .append( \"Thanks for \" + event.type + \"ing.\" )\n\n      // The clicked element is `event.target`,\n      // and its type is \"button\"\n      .append( \"the \" + event.target.type + \".\" );\n  }\n};\n\nvar you = { type: \"cat\" };\nvar they = { type: \"fish\" };\n\n// Set up handler to execute me.test() in the context\n// of `me`, with `you` and `they` as additional arguments\nvar proxy = $.proxy( me.test, me, you, they );\n\n$( \"#test\" )\n  .on( \"click\", proxy );\n"}],"longdesc":"\n    <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>\n    <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.</p>\n    <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>\n    <p><strong>As of jQuery 1.9</strong>, when the <code>context</code> is <code>null</code> or <code>undefined</code> the proxied function will be called with the same <code>this</code> object as the proxy was called with. This allows <code>$.proxy()</code> to be used to partially apply the arguments of a function without changing the context.</p>\n  "}]}