Skip to content

delegate: Document the method was deprecated in jQuery 3 #948

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
AurelioDeRosa wants to merge 3 commits into from
Closed

delegate: Document the method was deprecated in jQuery 3 #948

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2d3641f
delegate: Document the method was deprecated in jQuery 3
AurelioDeRosa Jul 10, 2016
bf744c4
Added bind, unbind, and undelegate
AurelioDeRosa Jul 10, 2016
d348113
Updates based on feedback
AurelioDeRosa Jul 17, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Added bind, unbind, and undelegate
  • Loading branch information
@AurelioDeRosa
AurelioDeRosa committed Jul 10, 2016
commit bf744c484d241b0bcda1162e817d960ced54001a
5 changes: 3 additions & 2 deletions entries/bind.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0"?>
<entry type="method" name="bind" return="jQuery">
<entry type="method" name="bind" return="jQuery" deprecated="3.0">
<title>.bind()</title>
<signature>
<added>1.0</added>
Expand Down Expand Up @@ -34,7 +34,7 @@
</signature>
<desc>Attach a handler to an event for the elements.</desc>
<longdesc>
<p>As of jQuery 1.7, the <a href="/on/"><code>.on()</code></a> method is the preferred method for attaching event handlers to a document. For earlier versions, the <code>.bind()</code> method is used for attaching an event handler directly to elements. Handlers are attached to the currently selected elements in the jQuery object, so those elements <em>must exist</em> at the point the call to <code>.bind()</code> occurs. For more flexible event binding, see the discussion of event delegation in <a href="/on/"><code>.on()</code></a> or <a href="/delegate/"><code>.delegate()</code></a>.</p>
<p>As of jQuery 3.0, <code>.bind()</code> has been deprecated. It was superseded by the <a href="/on/"><code>.on()</code></a> method for attaching event handlers to a document since jQuery 1.7, so its use was already discouraged. For earlier versions, the <code>.bind()</code> method is used for attaching an event handler directly to elements. Handlers are attached to the currently selected elements in the jQuery object, so those elements <em>must exist</em> at the point the call to <code>.bind()</code> occurs. For more flexible event binding, see the discussion of event delegation in <a href="/on/"><code>.on()</code></a> or <a href="/delegate/"><code>.delegate()</code></a>.</p>
Copy link
Copy Markdown
Member

@mgol mgol Jul 13, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't direct people to docs for deprecated APIs so I'd remove the reference to https://api.jquery.com/delegate/.

Copy link
Copy Markdown
Member Author

@AurelioDeRosa AurelioDeRosa Jul 17, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The method is available anyway, so removing the link only add frustration in having to open a new tab, searching for the method, and then read the doc. We've already stated the correct method to use is .on().

Copy link
Copy Markdown
Member

@mgol mgol Jul 17, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But why would anyone search for docs for this method? Most likely because they use .delegate() which can't be said about all the readers of the .bind() docs.

I think we shouldn't link to pages about deprecated APIs, they should serve first as a warning to not use the API and second as docs for the API for people that already use it in their code. If there is useful info about event delegation there that's not available on the .on() page it should just be moved to the .on() page so that it's not required to look at pages for deprecated APIs to learn something generally useful.

(to clarify, I wanted to have the .delegate() mention removed completely, not just the link to the page)

Copy link
Copy Markdown
Member

@mgol mgol Jul 30, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@AurelioDeRosa Hey, do you have any remarks to my comment? For me this is the only thing left before this can be landed.

Copy link
Copy Markdown
Member

@mgol mgol Aug 23, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@AurelioDeRosa Ping? We need this PR to land to unbreak the build.

@jquery/core @jquery/content any opinion on my comments? I need someone to agree with either of us so that we can land it.

Copy link
Copy Markdown
Member

@dmethvin dmethvin Aug 23, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The main reason someone might search specifically for .delegate() would be to figure out how to convert a call to .on(). That wouldn't apply for this reference. Any explanation of delegated events in .delegate() should be duplicated in .on(), I think it already should be there but if not we can open a new ticket to fix it.

If #971 can be addressed adequately (e.g. via a watermark) there wouldn't be any doubt about the method being deprecated and/or removed. As I mentioned in #972 I think there might be good reasons to keep, for example, the click-specific information in the .click() method docs, but that doesn't apply here either.

Copy link
Copy Markdown
Member

@mgol mgol Aug 24, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dmethvin As I understand you, you agree with me it's best not to link to .delegate() here? I'll go ahead & remove the link and land it then so that we have an unbroken build.

<p>Any string is legal for <code>eventType</code>; if the string is not the name of a native DOM event, then the handler is bound to a custom event. These events are never called by the browser, but may be triggered manually from other JavaScript code using <code>.trigger()</code> or <code>.triggerHandler()</code>.</p>
<p>If the <code>eventType</code> string contains a period (<code>.</code>) character, then the event is namespaced. The period character separates the event from its namespace. For example, in the call <code>.bind( "click.name", handler )</code>, the string <code>click</code> is the event type, and the string <code>name</code> is the namespace. Namespacing allows us to unbind or trigger some events of a type without affecting others. See the discussion of <code>.unbind()</code> for more information.</p>
<p>There are shorthand methods for some standard browser events such as <a href="/click/"><code>.click()</code></a> that can be used to attach or trigger event handlers. For a complete list of shorthand methods, see the <a href="/category/events/">events category</a>.</p>
Expand Down Expand Up @@ -259,4 +259,5 @@ $( "div.test" ).bind({
<category slug="version/1.0"/>
<category slug="version/1.4"/>
<category slug="version/1.4.3"/>
<category slug="deprecated/deprecated-3.0"/>
</entry>
2 changes: 1 addition & 1 deletion entries/delegate.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@
</argument>
</signature>
<longdesc>
<p>As of jQuery 3.0, <code>.delegate()</code> has been deprecated. It was superseded by the <a href="/on/">.on()</a> method since jQuery 1.7, so its use was already discouraged. For earlier versions, however, it remains the most effective means to use event delegation. More information on event binding and delegation is in the <a href="/on/">.on()</a> method. In general, these are the equivalent templates for the two methods:</p>
<p>As of jQuery 3.0, <code>.delegate()</code> has been deprecated. It was superseded by the <a href="/on/"><code>.on()</code></a> method since jQuery 1.7, so its use was already discouraged. For earlier versions, however, it remains the most effective means to use event delegation. More information on event binding and delegation is in the <a href="/on/"><code>.on()</code></a> method. In general, these are the equivalent templates for the two methods:</p>
<pre><code>
// jQuery 1.4.3+
$( elements ).delegate( selector, events, data, handler );
Expand Down
6 changes: 4 additions & 2 deletions entries/unbind.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0"?>
<entry type="method" name="unbind" return="jQuery">
<entry type="method" name="unbind" return="jQuery" deprecated="3.0">
<title>.unbind()</title>
<desc>Remove a previously-attached event handler from the elements.</desc>
<signature>
Expand Down Expand Up @@ -31,7 +31,8 @@
<added>1.0</added>
</signature>
<longdesc>
<p>Event handlers attached with <code>.bind()</code> can be removed with <code>.unbind()</code>. (As of jQuery 1.7, the <a href="/on/"><code>.on()</code></a> and <a href="/off/"><code>.off()</code></a> methods are preferred to attach and remove event handlers on elements.) In the simplest case, with no arguments, <code>.unbind()</code> removes all handlers attached to the elements:</p>
<p>Event handlers attached with <code>.bind()</code> can be removed with <code>.unbind()</code>. As of jQuery 3.0, <code>.unbind()</code> has been deprecated. It was superseded by the <a href="/off/"><code>.off()</code></a> method since jQuery 1.7, so its use was already discouraged.</p>
<p>In the simplest case, with no arguments, <code>.unbind()</code> removes all handlers attached to the elements:</p>
<pre><code>
$( "#foo" ).unbind();
</code></pre>
Expand Down Expand Up @@ -155,4 +156,5 @@ $( "p" ).unbind( "click", foo ); // ... foo will no longer be called.
<category slug="events/event-handler-attachment"/>
<category slug="version/1.0"/>
<category slug="version/1.4.3"/>
<category slug="deprecated/deprecated-3.0"/>
</entry>
5 changes: 3 additions & 2 deletions entries/undelegate.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0"?>
<entry type="method" name="undelegate" return="jQuery">
<entry type="method" name="undelegate" return="jQuery" deprecated="3.0">
<title>.undelegate()</title>
<desc>Remove a handler from the event for all elements which match the current selector, based upon a specific set of root elements.</desc>
<signature>
Expand Down Expand Up @@ -43,7 +43,7 @@
</argument>
</signature>
<longdesc>
<p>The <code>.undelegate()</code> method is a way of removing event handlers that have been bound using <a href="/delegate/"><code>.delegate()</code></a>. <strong>As of jQuery 1.7</strong>, the <a href="/on/"><code>.on()</code></a> and <a href="/off/"><code>.off()</code></a> methods are preferred for attaching and removing event handlers.</p>
<p>The <code>.undelegate()</code> method is a way of removing event handlers that have been bound using <a href="/delegate/"><code>.delegate()</code></a>. As of jQuery 3.0, <code>.undelegate()</code> has been deprecated. It was superseded by the <a href="/off/"><code>.off()</code></a> method since jQuery 1.7, so its use was already discouraged.</p>
Copy link
Copy Markdown
Member

@mgol mgol Jul 13, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The deprecation message should appear first, before any description of the API. See e.g. https://api.jquery.com/live/. This applies to the unbind page as well.

Copy link
Copy Markdown
Member Author

@AurelioDeRosa AurelioDeRosa Jul 17, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

</longdesc>
<example>
<desc>Can bind and unbind events to the colored button.</desc>
Expand Down Expand Up @@ -124,4 +124,5 @@ $( "form" ).undelegate( ".whatever" );
<category slug="version/1.4.2"/>
<category slug="version/1.4.3"/>
<category slug="version/1.6"/>
<category slug="deprecated/deprecated-3.0"/>
</entry>