1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
<!DOCTYPE html>
<html lang='en'><head><meta http-equiv='content-type' content='text/html; charset=UTF-8' /></head><body>
<div class="entry-content">
<div class="entry-title roundTop">
<h1 class="jq-clearfix">jQuery.extend()</h1>
<div class="entry-meta jq-clearfix">
Categories:
<span class="category"><a href="http://api.jquery.com/category/utilities/" title="View all posts in Utilities">Utilities</a></span>
</div>
</div>
<div id="jQuery-extend1" class="entry method">
<h2 class="jq-clearfix roundTop section-title">
<span class="name">jQuery.extend( target [, object1] [, objectN] )</span> <span class="returns">Returns: <a class="return" href="http://api.jquery.com/Types/#Object">Object</a></span>
</h2>
<div class="jq-box roundBottom entry-details">
<p class="desc"><strong>Description: </strong>Merge the contents of two or more objects together into the first object.</p>
<ul class="signatures">
<li class="signature" id="jQuery-extend-target-object1-objectN">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>jQuery.extend( target [, object1] [, objectN] )</h4>
<p class="arguement"><strong>target</strong> An object that will receive the new properties if additional objects are passed in or that will extend the jQuery namespace if it is the sole argument.</p>
<p class="arguement"><strong>object1</strong>An object containing additional properties to merge in.</p>
<p class="arguement"><strong>objectN</strong>Additional objects containing properties to merge in.</p>
</li>
<li class="signature" id="jQuery-extend-deep-target-object1-objectN">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.1.4/">1.1.4</a></span>jQuery.extend( [deep], target, object1 [, objectN] )</h4>
<p class="arguement"><strong>deep</strong>If true, the merge becomes recursive (aka. deep copy).</p>
<p class="arguement"><strong>target</strong>The object to extend. It will receive the new properties.</p>
<p class="arguement"><strong>object1</strong>An object containing additional properties to merge in.</p>
<p class="arguement"><strong>objectN</strong>Additional objects containing properties to merge in.</p>
</li>
</ul>
<div class="longdesc">
<p>When we supply two or more objects to <code>$.extend()</code>, properties from all of the objects are added to the target object.</p>
<p>If only one argument is supplied to <code>$.extend()</code>, this means the target argument was omitted. In this case, the jQuery object itself is assumed to be the target. By doing this, we can add new functions to the jQuery namespace. This can be useful for plugin authors wishing to add new methods to JQuery.</p>
<p>Keep in mind that the target object (first argument) will be modified, and will also be returned from <code>$.extend()</code>. If, however, we want to preserve both of the original objects, we can do so by passing an empty object as the target:</p>
<pre>var object = $.extend({}, object1, object2);</pre>
<p>The merge performed by <code>$.extend()</code> is not recursive by default; if a property of the first object is itself an object or array, it will be completely overwritten by a property with the same key in the second object. The values are not merged. This can be seen in the example below by examining the value of banana. However, by passing <code>true</code> for the first function argument, objects will be recursively merged.</p>
<p>Undefined properties are not copied. However, properties inherited from the object's prototype <em>will</em> be copied over. For performance reasons, properties that have values of built-in JavaScript types such as Date or RegExp are not re-constructed, and will appear as plain Objects in the resulting object or array.</p>
<blockquote>
<p><strong>Note:</strong> When performing a deep extend, Object and Array are extended, however primitive types such string, boolean and number are not. For specific needs that fall outside of this behaviour, it is recommended to write a custom extend method as this will be significantly faster from a performance perspective. </p>
</blockquote>
</div>
<h3>Examples:</h3>
<div class="entry-examples" id="entry-examples">
<div id="example-0">
<h4>Example: <span class="desc">Merge two objects, modifying the first.</span>
</h4>
<pre class="prettyprint"><code class="example demo-code"><!DOCTYPE html>
<html>
<head>
<script src="http://code.jquery.com/jquery-1.7rc2.js"></script>
</head>
<body>
<div id="log"></div>
<script>
var object1 = {
apple: 0,
banana: {weight: 52, price: 100},
cherry: 97
};
var object2 = {
banana: {price: 200},
durian: 100
};
/* merge object2 into object1 */
$.extend(object1, object2);
var printObj = function(obj) {
var arr = [];
$.each(obj, function(key, val) {
var next = key + ": ";
next += $.isPlainObject(val) ? printObj(val) : val;
arr.push( next );
});
return "{ " + arr.join(", ") + " }";
};
$("#log").append( printObj(object1) );
</script>
</body>
</html></code></pre>
<h4>Demo:</h4>
<div class="demo code-demo"></div>
</div>
<div id="example-1">
<h4>Example: <span class="desc">Merge two objects recursively, modifying the first.</span>
</h4>
<pre class="prettyprint"><code class="example demo-code"><!DOCTYPE html>
<html>
<head>
<script src="http://code.jquery.com/jquery-1.7rc2.js"></script>
</head>
<body>
<div id="log"></div>
<script>
var object1 = {
apple: 0,
banana: {weight: 52, price: 100},
cherry: 97
};
var object2 = {
banana: {price: 200},
durian: 100
};
/* merge object2 into object1, recursively */
$.extend(true, object1, object2);
var printObj = function(obj) {
var arr = [];
$.each(obj, function(key, val) {
var next = key + ": ";
next += $.isPlainObject(val) ? printObj(val) : val;
arr.push( next );
});
return "{ " + arr.join(", ") + " }";
};
$("#log").append( printObj(object1) );
</script>
</body>
</html></code></pre>
<h4>Demo:</h4>
<div class="demo code-demo"></div>
</div>
<div id="example-2">
<h4>Example: <span class="desc">Merge defaults and options, without modifying the defaults. This is a common plugin development pattern.</span>
</h4>
<pre class="prettyprint"><code class="example demo-code"><!DOCTYPE html>
<html>
<head>
<script src="http://code.jquery.com/jquery-1.7rc2.js"></script>
</head>
<body>
<div id="log"></div>
<script>
var defaults = { validate: false, limit: 5, name: "foo" };
var options = { validate: true, name: "bar" };
/* merge defaults and options, without modifying defaults */
var settings = $.extend({}, defaults, options);
var printObj = function(obj) {
var arr = [];
$.each(obj, function(key, val) {
var next = key + ": ";
next += $.isPlainObject(val) ? printObj(val) : val;
arr.push( next );
});
return "{ " + arr.join(", ") + " }";
};
$("#log").append( "<div><b>settings -- </b>" + printObj(settings) + "</div>" );
$("#log").append( "<div><b>options -- </b>" + printObj(options) + "</div>" );
</script>
</body>
</html></code></pre>
<h4>Demo:</h4>
<div class="demo code-demo"></div>
</div>
</div>
</div>
</div>
</div>
</body></html>
|
