Skip to content

Commit b819a49

Browse files
kevin-brownkevin-brown
committed
Added compatibility section
This is the same as the old documentation, it has not been transformed into a FAQ yet.
1 parent 84d1218 commit b819a49

7 files changed

Lines changed: 211 additions & 0 deletions

File tree

‎docs/_includes/options-new/compatibility.html‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<section>
2+
<h1>
3+
Backwards compatibility
4+
</h1>
5+
6+
{% include options-new/compatibility/matcher.html %}
7+
{% include options-new/compatibility/initial-selection.html %}
8+
{% include options-new/compatibility/query-function.html %}
9+
{% include options-new/compatibility/text-input.html %}
10+
</section>

‎docs/_includes/options-new/compatibility/initial-selection.html‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
<section>
2+
<h2 id="initSelection">
3+
Old initial selections with <code>initSelection</code>
4+
</h2>
5+
6+
<p class="alert alert-warning">
7+
<a href="announcements-4.0.html#removed-initselection" class="alert-link">Deprecated in Select2 4.0.</a>
8+
This has been replaced by another option and is only available in the
9+
<a href="index.html#builds-full" class="alert-link">full builds</a> of
10+
Select2.
11+
</p>
12+
13+
<p>
14+
In the past, Select2 required an option called <code>initSelection</code>
15+
that was defined whenever a custom data source was being used, allowing
16+
for the initial selection for the component to be determined. This has
17+
been replaced by the <code>current</code> method on the
18+
<a href="#dataAdapter">data adapter</a>.
19+
</p>
20+
21+
<div class="row">
22+
<div class="col-sm-6">
23+
<dl class="dl-horizontal">
24+
<dt>Key</dt>
25+
<dd>
26+
<code>initSelection</code>
27+
</dd>
28+
29+
<dt>Value</dt>
30+
<dd>
31+
A function taking a <code>callback</code>
32+
</dd>
33+
</dl>
34+
</div>
35+
36+
<div class="col-sm-6">
37+
<dl class="dl-horizontal">
38+
<dt>Adapter</dt>
39+
<dd>
40+
<code title="select2/data/base">DataAdapter</code>
41+
</dd>
42+
43+
<dt>Decorator</dt>
44+
<dd>
45+
<code title="select2/compat/initSelection">InitSelection</code>
46+
</dd>
47+
</dl>
48+
</div>
49+
</div>
50+
</section>

‎docs/_includes/options-new/compatibility/introduction.html‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<section>
2+
<p>
3+
Select2 offers limited backwards compatibility with the previously 3.5.x
4+
release line, allowing people more efficiently transfer across releases
5+
and get the latest features. For many of the larger changes, such as the
6+
change in how custom data adapters work, compatibility modules were
7+
created that will be used to assist in the upgrade process. It is not
8+
recommended to rely on these compatibility modules, as they will not
9+
always exist, but they make upgrading easier for major changes.
10+
</p>
11+
12+
<p>
13+
<strong>The compatibility modules are only included in the
14+
<a href="index.html#builds-full" class="alert-link">full builds</a> of
15+
Select2</strong>. These files end in <code>.full.js</code>, and the
16+
compatibility modules are prefixed with <code>select2/compat</code>.
17+
</p>
18+
</section>

‎docs/_includes/options-new/compatibility/matcher.html‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
<section>
2+
<h2 id="compat-matcher">
3+
Simplified function for matching data objects
4+
</h2>
5+
6+
<p class="alert alert-info">
7+
<a href="announcements-4.0.html#new-matcher" class="alert-link">Added in Select2 4.0.0.</a>
8+
This method was added to make upgrading easier from earlier versions of
9+
Select2.
10+
</p>
11+
12+
<p>
13+
During the <a href="announcements-4.0.html">Select2 4.0.0 release</a>, the
14+
<code>matcher</code> function was changed to allow for more complex
15+
matching of nested objects.
16+
</p>
17+
18+
<div class="row">
19+
<div class="col-sm-6">
20+
<dl class="dl-horizontal">
21+
<dt>Key</dt>
22+
<dd>
23+
<code>matcher</code>
24+
</dd>
25+
26+
<dt>Value</dt>
27+
<dd>
28+
A function taking a search <code>term</code> and the data object
29+
<code>text</code>.
30+
</dd>
31+
</dl>
32+
</div>
33+
34+
<div class="col-sm-6">
35+
<dl class="dl-horizontal">
36+
<dt>Adapter</dt>
37+
<dd>
38+
<code title="select2/compat/matcher">oldMatcher</code>
39+
</dd>
40+
</dl>
41+
</div>
42+
</div>
43+
44+
<p>
45+
The <a href="examples.html#matcher">custom matcher example</a> provides a
46+
guide for how to use this in your own application. For those upgrading
47+
from older versions of Select2, you just need to wrap your old
48+
<code>matcher</code> with this function to maintain compatibility.
49+
</p>
50+
</section>

‎docs/_includes/options-new/compatibility/query-function.html‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
<section>
2+
<h2 id="query">
3+
Querying old data with <code>query</code>
4+
</h2>
5+
6+
<p class="alert alert-warning">
7+
<a href="announcements-4.0.html#query-to-data-adapter" class="alert-link">Deprecated in Select2 4.0.</a>
8+
This has been replaced by another option and is only available in the
9+
<a href="index.html#builds-full" class="alert-link">full builds</a> of
10+
Select2.
11+
</p>
12+
13+
<p>
14+
In the past, Select2 supported an option called <code>query</code> that
15+
allowed for a custom data source to be used. This option has been replaced
16+
by the <code>query</code> method on the
17+
<a href="#dataAdapter">data adapter</a> and takes a very similar set of
18+
parameters.
19+
</p>
20+
21+
<div class="row">
22+
<div class="col-sm-6">
23+
<dl class="dl-horizontal">
24+
<dt>Key</dt>
25+
<dd>
26+
<code>query</code>
27+
</dd>
28+
29+
<dt>Value</dt>
30+
<dd>
31+
A function taking <code>params</code> (including a <code>callback</code>)
32+
</dd>
33+
</dl>
34+
</div>
35+
36+
<div class="col-sm-6">
37+
<dl class="dl-horizontal">
38+
<dt>Adapter</dt>
39+
<dd>
40+
<code title="select2/data/base">DataAdapter</code>
41+
</dd>
42+
43+
<dt>Decorator</dt>
44+
<dd>
45+
<code title="select2/compat/query">Query</code>
46+
</dd>
47+
</dl>
48+
</div>
49+
</div>
50+
</section>

‎docs/_includes/options-new/compatibility/text-input.html‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
<section>
2+
<h2 id="input-fallback">
3+
Compatibility with <code>&lt;input type="text" /&gt;</code>
4+
</h2>
5+
6+
<p class="alert alert-warning">
7+
<a href="announcements-4.0.html#hidden-input" class="alert-link">Deprecated in Select2 4.0.</a>
8+
It is now encouraged to use the <code>&lt;select&gt;</code> tag instead.
9+
</p>
10+
11+
<p>
12+
In past versions of Select2, a <code>&lt;select&gt;</code> element could
13+
only be used with a limited subset of options. An
14+
<code>&lt;input type="hidden" /&gt;</code> was required instead, which did
15+
not allow for a graceful fallback for users who did not have JavaScript
16+
enabled. Select2 now supports the <code>&lt;select&gt;</code> element for
17+
all options, so it is no longer required to use <code>&lt;input /&gt;</code>
18+
elements with Select2.
19+
</p>
20+
21+
<dl class="dl-horizontal">
22+
<dt>Adapter</dt>
23+
<dd>
24+
<code title="select2/data/base">DataAdapter</code>
25+
</dd>
26+
27+
<dt>Decorator</dt>
28+
<dd>
29+
<code title="select2/compat/inputData">InputData</code>
30+
</dd>
31+
</dl>
32+
</section>

‎docs/options-new.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ <h1>
2424
{% include options-new/selections.html %}
2525
{% include options-new/dropdown.html %}
2626
{% include options-new/events.html %}
27+
{% include options-new/compatibility.html %}
2728
</div>
2829
<div class="col-md-3" role="complementary">
2930
{% include nav/options-new.html %}

0 commit comments

Comments
 (0)