Added documentation for <input type="text" />

This adds basic documentation explaining that there are compatibility
decorators for `<input type="text" />` support. This is not fully
compatible with all features and requires the use of an external
adapter like the `ArrayAdapter` or `AjaxAdapter` to provide a
reasonable way to query results.

This also triggers a warning if the adapter is used with a hidden
input, as the degraded functionality when there is no JavaScript
support should be discouraged.

Author: kevin-brown

dist/js/select2.amd.full.js

@@ -4993,6 +4993,16 @@ define('select2/compat/inputData',[
     this._currentData = [];
     this._valueSeparator = options.get('valueSeparator') || ',';
 
+    if ($element.prop('type') === 'hidden') {
+      if (console && console.warn) {
+        console.warn(
+          'Select2: Using a hidden input with Select2 is no longer ' +
+          'supported and may stop working in the future. It is recommended ' +
+          'to use a `<select>` element instead.'
+        );
+      }
+    }
+
     decorated.call(this, $element, options);
   }
 

dist/js/select2.full.js

@@ -5432,6 +5432,16 @@ define('select2/compat/inputData',[
     this._currentData = [];
     this._valueSeparator = options.get('valueSeparator') || ',';
 
+    if ($element.prop('type') === 'hidden') {
+      if (console && console.warn) {
+        console.warn(
+          'Select2: Using a hidden input with Select2 is no longer ' +
+          'supported and may stop working in the future. It is recommended ' +
+          'to use a `<select>` element instead.'
+        );
+      }
+    }
+
     decorated.call(this, $element, options);
   }
 

dist/js/select2.full.min.js

@@ -1588,6 +1588,38 @@ <h2 id="query">
       </div>
     </div>
   </section>
+
+  <h2 id="input-fallback">
+    Compatibility with <code>&lt;input type="text" /&gt;</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>&lt;select&gt;</code> tag instead.
+  </p>
+
+  <p>
+    In past versions of Select2, a <code>&lt;select&gt;</code> element could
+    only be used with a limited subset of options. An
+    <code>&lt;input type="hidden" /&gt;</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>&lt;select&gt;</code> element for
+    all options, so it is no longer required to use <code>&lt;input /&gt;</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>
 </div>
 
 <script type="text/javascript">

docs/options.html

@@ -5,6 +5,16 @@ define([
     this._currentData = [];
     this._valueSeparator = options.get('valueSeparator') || ',';
 
+    if ($element.prop('type') === 'hidden') {
+      if (console && console.warn) {
+        console.warn(
+          'Select2: Using a hidden input with Select2 is no longer ' +
+          'supported and may stop working in the future. It is recommended ' +
+          'to use a `<select>` element instead.'
+        );
+      }
+    }
+
     decorated.call(this, $element, options);
   }