You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Jan 16, 2020. It is now read-only.
Copy file name to clipboardExpand all lines: README.md
+23-44Lines changed: 23 additions & 44 deletions
Original file line number
Diff line number
Diff 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>
20
2
21
3
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').
22
4
23
-
h2(#mutate). Mutation Events
24
-
5
+
<h2>Mutation Events</h2>
25
6
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.
26
7
27
-
h3(#attrchange). attrChange
8
+
<h3>attrChange</h3>
28
9
29
10
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.
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.
78
59
@@ -91,7 +72,7 @@ $("#el")
91
72
.attr("foo", "bar");
92
73
</pre>
93
74
94
-
h3(#arraychange). arrayChange
75
+
<h3>arrayChange</h3>
95
76
96
77
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.
97
78
@@ -122,16 +103,16 @@ $.push(arr, 4, 5);
122
103
$.splice(arr, 0, 1);
123
104
</pre>
124
105
125
-
h3(#arraychanging). arrayChanging
106
+
<h3>arrayChanging</h3>
126
107
127
108
Exactly like the attrChanging event, but for arrays. Operation can be cancelled via the ev.preventDefault() method.
128
109
129
110
130
-
h2(#linking). Linking Objects
111
+
<h2>Linking Objects<h2>
131
112
132
113
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).
133
114
134
-
h3(#link). jQuery.link
115
+
<h3>jQuery.link</h3>
135
116
136
117
Sets up a link that pushes changes to any of the source objects to all target objects.
The 'source' may be an object, DOM element, or string selector.
151
-
*object*
132
+
<strong>object</strong>
152
133
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>
154
135
155
-
*DOM element or selector*
136
+
<strong>DOM element or selector</strong>
156
137
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.
157
138
158
139
<pre>
@@ -162,7 +143,7 @@ $.link({
162
143
});
163
144
</pre>
164
145
165
-
*Attributes and Microdata*
146
+
<strong>Attributes and Microdata</strong>
166
147
The 'sourceAttr' and 'targetAttr' fields are optional. If omitted, the attribute is determined automatically:
167
148
168
149
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
$.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.
195
176
@@ -225,11 +206,11 @@ $.link({
225
206
});
226
207
</pre>
227
208
228
-
*twoWay*
209
+
<strong>twoWay</strong>
229
210
230
211
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).
231
212
232
-
*Updating immediately*
213
+
<strong>Updating immediately</strong>
233
214
234
215
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:
235
216
@@ -246,11 +227,11 @@ $.link({
246
227
});
247
228
</pre>
248
229
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.
250
231
251
232
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.
252
233
253
-
*Context*
234
+
<strong>Context</strong>
254
235
255
236
$.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:
256
237
@@ -275,7 +256,7 @@ $.link({
275
256
276
257
</pre>
277
258
278
-
h3(#unlink). jQuery.unlink
259
+
<h3>jQuery.unlink</h3>
279
260
280
261
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.
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.
$.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:
299
280
@@ -310,11 +291,11 @@ $.liveLink({
310
291
311
292
Note however that currently you cannot use 'twoWay' on a live link. You may use 'update'.
312
293
313
-
h3(#livelink). jQuery.unlinkLive
294
+
<h3>jQuery.unlinkLive</h3>
314
295
315
296
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.
316
297
317
-
h3(#converting). Conversion and jQuery.convertFn
298
+
<h3>Conversion and jQuery.convertFn</h3>
318
299
319
300
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.
0 commit comments