backwards-compatibility.html
5.91 KB
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
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
<section>
<div class="page-header">
<h1 id="compatibility">Backwards compatibility</h1>
</div>
<p>
Select2 offers limited backwards compatibility with the previously 3.5.x
release line, allowing people more efficiently transfer across releases
and get the latest features. For many of the larger changes, such as the
change in how custom data adapters work, compatibility modules were
created that will be used to assist in the upgrade process. It is not
recommended to rely on these compatibility modules, as they will not
always exist, but they make upgrading easier for major changes.
</p>
<p>
<strong>The compatibility modules are only included in the
<a href="index.html#builds-full" class="alert-link">full builds</a> of
Select2</strong>. These files end in <code>.full.js</code>, and the
compatibility modules are prefixed with <code>select2/compat</code>.
</p>
<h2 id="compat-matcher">
Simplified function for matching data objects
</h2>
<p class="alert alert-info">
<a href="announcements-4.0.html#new-matcher" class="alert-link">Added in Select2 4.0.0.</a>
This method was added to make upgrading easier from earlier versions of
Select2.
</p>
<p>
During the <a href="announcements-4.0.html">Select2 4.0.0 release</a>, the
<code>matcher</code> function was changed to allow for more complex
matching of nested objects.
</p>
<div class="row">
<div class="col-sm-6">
<dl class="dl-horizontal">
<dt>Key</dt>
<dd>
<code>matcher</code>
</dd>
<dt>Value</dt>
<dd>
A function taking a search <code>term</code> and the data object
<code>text</code>.
</dd>
</dl>
</div>
<div class="col-sm-6">
<dl class="dl-horizontal">
<dt>Adapter</dt>
<dd>
<code title="select2/compat/matcher">oldMatcher</code>
</dd>
</dl>
</div>
</div>
<p>
The <a href="examples.html#matcher">custom matcher example</a> provides a
guide for how to use this in your own application. For those upgrading
from older versions of Select2, you just need to wrap your old
<code>matcher</code> with this function to maintain compatibility.
</p>
<h2 id="initSelection">
Old initial selections with <code>initSelection</code>
</h2>
<p class="alert alert-warning">
<a href="announcements-4.0.html#removed-initselection" class="alert-link">Deprecated in Select2 4.0.</a>
This has been replaced by another option and is only available in the
<a href="index.html#builds-full" class="alert-link">full builds</a> of
Select2.
</p>
<p>
In the past, Select2 required an option called <code>initSelection</code>
that was defined whenever a custom data source was being used, allowing
for the initial selection for the component to be determined. This has
been replaced by the <code>current</code> method on the
<a href="#dataAdapter">data adapter</a>.
</p>
<div class="row">
<div class="col-sm-6">
<dl class="dl-horizontal">
<dt>Key</dt>
<dd>
<code>initSelection</code>
</dd>
<dt>Value</dt>
<dd>
A function taking a <code>callback</code>
</dd>
</dl>
</div>
<div class="col-sm-6">
<dl class="dl-horizontal">
<dt>Adapter</dt>
<dd>
<code title="select2/data/base">DataAdapter</code>
</dd>
<dt>Decorator</dt>
<dd>
<code title="select2/compat/initSelection">InitSelection</code>
</dd>
</dl>
</div>
</div>
<h2 id="query">
Querying old data with <code>query</code>
</h2>
<p class="alert alert-warning">
<a href="announcements-4.0.html#query-to-data-adapter" class="alert-link">Deprecated in Select2 4.0.</a>
This has been replaced by another option and is only available in the
<a href="index.html#builds-full" class="alert-link">full builds</a> of
Select2.
</p>
<p>
In the past, Select2 supported an option called <code>query</code> that
allowed for a custom data source to be used. This option has been replaced
by the <code>query</code> method on the
<a href="#dataAdapter">data adapter</a> and takes a very similar set of
parameters.
</p>
<div class="row">
<div class="col-sm-6">
<dl class="dl-horizontal">
<dt>Key</dt>
<dd>
<code>query</code>
</dd>
<dt>Value</dt>
<dd>
A function taking <code>params</code> (including a <code>callback</code>)
</dd>
</dl>
</div>
<div class="col-sm-6">
<dl class="dl-horizontal">
<dt>Adapter</dt>
<dd>
<code title="select2/data/base">DataAdapter</code>
</dd>
<dt>Decorator</dt>
<dd>
<code title="select2/compat/query">Query</code>
</dd>
</dl>
</div>
</div>
<h2 id="input-fallback">
Compatibility with <code><input type="text" /></code>
</h2>
<p class="alert alert-warning">
<a href="announcements-4.0.html#hidden-input" class="alert-link">Deprecated in Select2 4.0.</a>
It is now encouraged to use the <code><select></code> tag instead.
</p>
<p>
In past versions of Select2, a <code><select></code> element could
only be used with a limited subset of options. An
<code><input type="hidden" /></code> was required instead, which did
not allow for a graceful fallback for users who did not have JavaScript
enabled. Select2 now supports the <code><select></code> element for
all options, so it is no longer required to use <code><input /></code>
elements with Select2.
</p>
<dl class="dl-horizontal">
<dt>Adapter</dt>
<dd>
<code title="select2/data/base">DataAdapter</code>
</dd>
<dt>Decorator</dt>
<dd>
<code title="select2/compat/inputData">InputData</code>
</dd>
</dl>
</section>