Added templating example

This also fixes the case where `templateResult` does not return a
string, where it will fall back to jQuery to set the value of the
option.  This allows for the `templateResult` function to return a
jQuery or DOM element that contains the templated data.

Just like with the translation methods, only strings returned from
`templateResult` will be escaped.

The old flag icons have been transferred from the old repository to
the documentation, for use in the templates.  Unfortunately I cannot
find a license for them, but I suspect a license isn't actually
needed considering the state flags are public.

This closes https://github.com/select2/select2/issues/3005.
This closes https://github.com/select2/select2/issues/818.

dist/js/select2.amd.full.js

@@ -731,8 +731,10 @@ define('select2/results',[
 
     if (content == null) {
       container.style.display = 'none';
-    } else {
+    } else if (typeof content === 'string') {
       container.innerHTML = escapeMarkup(content);
+    } else {
+      $(container).append(content);
     }
   };
 

dist/js/select2.amd.js

@@ -731,8 +731,10 @@ define('select2/results',[
 
     if (content == null) {
       container.style.display = 'none';
-    } else {
+    } else if (typeof content === 'string') {
       container.innerHTML = escapeMarkup(content);
+    } else {
+      $(container).append(content);
     }
   };
 

dist/js/select2.full.js

@@ -1169,8 +1169,10 @@ define('select2/results',[
 
     if (content == null) {
       container.style.display = 'none';
-    } else {
+    } else if (typeof content === 'string') {
       container.innerHTML = escapeMarkup(content);
+    } else {
+      $(container).append(content);
     }
   };
 

dist/js/select2.js

@@ -1169,8 +1169,10 @@ define('select2/results',[
 
     if (content == null) {
       container.style.display = 'none';
-    } else {
+    } else if (typeof content === 'string') {
       container.innerHTML = escapeMarkup(content);
+    } else {
+      $(container).append(content);
     }
   };
 

docs/examples.html

@@ -7,6 +7,13 @@ slug: examples
 <script type="text/javascript" src="vendor/js/placeholders.jquery.min.js"></script>
 <script type="text/javascript" src="dist/js/i18n/es.js"></script>
 
+<style type="text/css">
+.img-flag {
+  height: 15px;
+  width: 18px;
+}
+</style>
+
 <div class="container">
   <section id="basic" class="row">
     <div class="col-md-4">
@@ -118,6 +125,52 @@ $(".js-example-placeholder-multiple").select2({
     </div>
   </section>
 
+  <section id="templating" class="row">
+    <div class="col-md-4">
+      <h1>Templating</h1>
+
+      <p>
+        Various display options of the Select2 component can be changed
+      </p>
+
+      <p>
+        <select class="js-example-templating js-states form-control"></select>
+      </p>
+
+      <p>
+        You can access the <code>&lt;option&gt;</code> element
+        (or <code>&lt;optgroup&gt;</code>) and any attributes on those elements
+        using <code>.element</code>.
+      </p>
+
+      <p>
+        Templating is primarily controlled by the
+        <a href="options.html#templateResult"><code>templateResult</code></a>
+        and <a href="options.html#templateSelection"><code>templateSelection</code></a>
+        options.
+      </p>
+    </div>
+    <div class="col-md-8">
+      <h2>Example code</h2>
+
+      <pre data-fill-from=".js-code-templating"></pre>
+
+<script type="text/x-example-code" class="js-code-templating">
+function formatState (state) {
+  if (!state.id) { return state.text; }
+  var $state = $(
+    '<span><img src="vendor/images/flags/' + state.element.value.toLowerCase() + '.png" class="img-flag" /> ' + state.text + '</span>'
+  );
+  return $state;
+};
+
+$(".js-example-templating").select2({
+  templateResult: formatState
+});
+</script>
+    </div>
+  </section>
+
   <section id="data-array" class="row">
     <div class="col-md-4">
       <h1>Loading array data</h1>
@@ -915,6 +968,26 @@ $.fn.select2.amd.require(
     maximumSelectionLength: 2
   });
 
+  function formatState (state) {
+    if (!state.id) {
+      return state.text;
+    }
+    var $state = $(
+      '<span>' +
+        '<img src="vendor/images/flags/' +
+          state.element.value.toLowerCase() +
+        '.png" class="img-flag" /> ' +
+        state.text +
+      '</span>'
+    );
+    return $state;
+  };
+
+  $(".js-example-templating").select2({
+    templateResult: formatState,
+    templateSelection: formatState
+  });
+
   $dataArray.select2({
     data: data
   });

src/js/select2/results.js

@@ -485,8 +485,10 @@ define([
 
     if (content == null) {
       container.style.display = 'none';
-    } else {
+    } else if (typeof content === 'string') {
       container.innerHTML = escapeMarkup(content);
+    } else {
+      $(container).append(content);
     }
   };