Skip to content
This repository was archived by the owner on Jan 16, 2020. It is now read-only.

Commit 1702fe8

Browse files
joefeserDave Reed
authored and
Dave Reed
committed
Cleaned up code to reflect correct html tags.
1 parent 2bb99f4 commit 1702fe8

File tree

1 file changed

+23
-44
lines changed

1 file changed

+23
-44
lines changed

README.md

Lines changed: 23 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,11 @@
1-
h1. Contents
2-
3-
* "Introduction":#introduction
4-
** "Mutation Events":#mutate
5-
*** "attrChange":#attrchange
6-
*** "attrChanging":#attrchanging
7-
*** "arrayChange":#arraychange
8-
*** "arrayChanging":#arraychanging
9-
** "Linking Objects":#linking
10-
*** "jQuery.link":#link
11-
*** "jQuery.unlink":#unlink
12-
*** "jQuery.linkLive":#linklive
13-
*** "jQuery.unlinkLive":#unlinklive
14-
*** "Conversion and jQuery.convertFn":#converting
15-
16-
* "Revision History":#revisionhistory
17-
* "Comments":#comments
18-
19-
h1(#introduction). Introduction
1+
<h1>Introduction</h1>
202

213
This proposal describes how support for "data linking" can be added to the jQuery core library. The term "data linking" is used here to mean "automatically linking the field of an object to another field of another object." That is to say, the two objects are "linked" to each other, where changing the value of one object (the 'source') automatically updates the value in the other object (the 'target').
224

23-
h2(#mutate). Mutation Events
24-
5+
<h2>Mutation Events</h2>
256
In order to link a source to a target, it is necessary to be notified when a data associated with the source object changes, so that it can be pushed onto the target object. This plugin adds some special events to jQuery to facilitiate this, which are also useful on their own.
267

27-
h3(#attrchange). attrChange
8+
<h3>attrChange</h3>
289

2910
The 'attrChange' event fires when an attribute of a DOM element or object is changed through the jQuery.fn.attr or jQuery.attr methods. An interesting feature of this plugin is that it specifically allows for jQuery.fn.attr to be usable on plain objects or arrays. The data(), bind(), and trigger() methods all work with plain objects, so this is a natural extension which already mostly works. However, a small change was necessary to jQuery.attr to avoid the special cases applied when the target is a plain object, like class->className, and readonly->readOnly, and that negative values of "width" are ignored, etc. So this plugin also makes it officially possible to use attr() to set fields of an object as you would expect.
3011

@@ -72,7 +53,7 @@ $("#el").attrChange("val", report)
7253
.val( 'bye' );
7354
</pre>
7455

75-
h3(#attrchanging). attrChanging
56+
<h3>attrChanging</h3>
7657

7758
The 'attrChanging' event fires when an attribute of a DOM element or object is about to be changed. The ev.preventDefault() method may be called in order to prevent the change from occuring.
7859

@@ -91,7 +72,7 @@ $("#el")
9172
.attr("foo", "bar");
9273
</pre>
9374

94-
h3(#arraychange). arrayChange
75+
<h3>arrayChange</h3>
9576

9677
Like the attrChange event, but fires when an Array is mutated through any of the new array mutation APIs. Information about what the mutation was is available on the event object.
9778

@@ -122,16 +103,16 @@ $.push(arr, 4, 5);
122103
$.splice(arr, 0, 1);
123104
</pre>
124105

125-
h3(#arraychanging). arrayChanging
106+
<h3>arrayChanging</h3>
126107

127108
Exactly like the attrChanging event, but for arrays. Operation can be cancelled via the ev.preventDefault() method.
128109

129110

130-
h2(#linking). Linking Objects
111+
<h2>Linking Objects<h2>
131112

132113
When objects are linked, changes to one are automatically forwarded to another. For example, this allows you to very quickly and easily link fields of a form to an object. Any changes to the form fields are automatically pushed onto the object, saving you from writing retrieval code. Furthermore, built-in support for converters lets you modify the format or type of the value as it flows between objects (for example, formatting a phone number, or parsing a string to a number).
133114

134-
h3(#link). jQuery.link
115+
<h3>jQuery.link</h3>
135116

136117
Sets up a link that pushes changes to any of the source objects to all target objects.
137118

@@ -148,11 +129,11 @@ alert(person.name); // <user typed value>
148129
</pre>
149130

150131
The 'source' may be an object, DOM element, or string selector.
151-
*object*
132+
<strong>object</strong>
152133
Changes to that object through a jQuery set wrapping it will trigger the link. e.g.:
153-
@$(obj).attr("foo", "bar");@
134+
<code>$(obj).attr("foo", "bar");</code>
154135

155-
*DOM element or selector*
136+
<strong>DOM element or selector</strong>
156137
This sets up a link from all the matching elements (if it is a selector) to all matching targets. For example, if there are 3 inputs and 3 spans on the page, 9 links are created, one from each input to each span.
157138

158139
<pre>
@@ -162,7 +143,7 @@ $.link({
162143
});
163144
</pre>
164145

165-
*Attributes and Microdata*
146+
<strong>Attributes and Microdata</strong>
166147
The 'sourceAttr' and 'targetAttr' fields are optional. If omitted, the attribute is determined automatically:
167148

168149
The source attribute is determined as follows:
@@ -189,7 +170,7 @@ For example, the following sets up a link that activates whenever the val() of t
189170
$.link( { source: "#input1", target: "#span1" } );
190171
</pre>
191172

192-
*From/To Syntax*
173+
<strong>From/To Syntax</strong>
193174

194175
$.link supports creating multiple links with different rules at the same time. In this example, two form elements are mapped to two different fields of the same object.
195176

@@ -225,11 +206,11 @@ $.link({
225206
});
226207
</pre>
227208

228-
*twoWay*
209+
<strong>twoWay</strong>
229210

230211
The twoWay option sets up links in both directions -- from source to target, and target to source. Changes in either will be reflected in the other. This is the reason for the 'convert' option on the 'to' settings -- those converters would be used when pushing changes from a target to a source (reverse).
231212

232-
*Updating immediately*
213+
<strong>Updating immediately</strong>
233214

234215
Sometimes it is desired that the target of a link reflect the source value immediately, even before the source is changed. You can tell link() to update the target immediately using the 'update' setting:
235216

@@ -246,11 +227,11 @@ $.link({
246227
});
247228
</pre>
248229

249-
Note that this is particularly useful when relying on the automatic target attribute determination. You can quickly populate an object with a form's current values by relying on @itemprop@ attributes or input @name@, and setting update to true to force an immediate update.
230+
Note that this is particularly useful when relying on the automatic target attribute determination. You can quickly populate an object with a form's current values by relying on <code>itemprop</code> attributes or input <code>name</code>, and setting update to true to force an immediate update.
250231

251232
Note that if you put 'update' on the 'from' settings, the source is updated with the target value, even though the link usually flows from the source to the target. This allows you, for example, to setup a link from an input to an object, but have the input initially reflect the value already in the target.
252233

253-
*Context*
234+
<strong>Context</strong>
254235

255236
$.link in both direct and from/to forms allows a 2nd jQuery context parameter. This context is used if any selectors are given. For example, these are equivalent:
256237

@@ -275,7 +256,7 @@ $.link({
275256

276257
</pre>
277258

278-
h3(#unlink). jQuery.unlink
259+
<h3>jQuery.unlink</h3>
279260

280261
This removes a link previously established with $.link. The syntax is exactly like $.link, including the from/to syntax, except that the 'convert' and 'update' parameters are not used. A link is identified by four pieces of data: source, sourceAttr, target, and targetAttr. Note that it is possible to remove only a portion of a link previously created. For example, assuming there are two elements on the page with css class "foo" (#foo1 and #foo2), the following creates two links -- one from each, then removes only one of them.
281262

@@ -284,7 +265,7 @@ $.link( { source: ".foo", target: target, targetAttr: "field" } );
284265
$.unlink( { source: "#foo1", target: target, targetAttr: "field" } );
285266
</pre>
286267

287-
*Automatic unlinking*
268+
<strong>Automatic unlinking</strong>
288269

289270
Links are cleaned up when its target or source is a DOM element that is being destroyed. For example, the following setups a link between an input and a span, then destroys the span by clearing it's parent html. The link is automatically removed.
290271

@@ -293,7 +274,7 @@ $.link( { source: "#input1", target: "#span1" } );
293274
$("#span1").parent().html("");
294275
</pre>
295276

296-
h3(#livelink). jQuery.linkLive
277+
<h3>jQuery.linkLive</h3>
297278

298279
$.liveLink is a powerful tool that links multiple elements now or in the future. For example, to map all the input fields of a form to an object, even when form fields are dynamically added in the future:
299280

@@ -310,11 +291,11 @@ $.liveLink({
310291

311292
Note however that currently you cannot use 'twoWay' on a live link. You may use 'update'.
312293

313-
h3(#livelink). jQuery.unlinkLive
294+
<h3>jQuery.unlinkLive</h3>
314295

315296
Removes a live link previously created with $.linkLive. Syntax is the same as unlink. Note that unlike regular links, live links do not expand into all the possible sources and targets when they are created. This means you cannot 'unliveLink' a portion of a live link, you may only remove the entire live link.
316297

317-
h3(#converting). Conversion and jQuery.convertFn
298+
<h3>Conversion and jQuery.convertFn</h3>
318299

319300
Often times, it is necessary to modify the value as it flows from one side of a link to the other. For example, to convert null to "None", to format or parse a date, or parse a string to a number. The link APIs support specifying a converter function, either as a name of a function defined on jQuery.convertFn, or as a function itself.
320301

@@ -372,12 +353,10 @@ alert($("#fullname").text()); // "jQuery User"
372353
</pre>
373354

374355

375-
h1(#revisionhistory). Revision History
356+
<h1>Revision History</h1>
376357

377358
* 5/26/2010 -- Completely revised the API based on forum feedback.
378359
* 5/01/2010 -- Corrected comments about restricted scope -- event is suppressed, not the change.
379360
* 5/01/2010 -- Fixed glitches in comments and added info about restricted scope.
380361
* 4/29/2010 -- Expanded on converter samples.
381362
* 4/28/2010 -- Initial proposal published
382-
383-
h1(#comments). Comments

0 commit comments

Comments
 (0)