From 7f8e9dc62a847ef63d38b8cd8f6e13f31bbb2115 Mon Sep 17 00:00:00 2001
From: Kevin Brown <kevin@kevin-brown.com>
Date: Sun, 14 Feb 2016 15:16:08 -0500
Subject: [PATCH] Document the change.select2 event

This closes https://github.com/select2/select2/issues/3620.
---
 docs/_includes/options/events/jquery.html | 31 ++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/docs/_includes/options/events/jquery.html b/docs/_includes/options/events/jquery.html
index dd28c077..8023909f 100644
--- a/docs/_includes/options/events/jquery.html
+++ b/docs/_includes/options/events/jquery.html
@@ -19,7 +19,36 @@
     What events does Select2 listen for?
   </h3>
 
-  {% include options/not-written.html %}
+  <p>
+    Select2 will listen for the <code>change</code> event on the
+    <code>&lt;select&gt;</code> that it is attached to. If you make any
+    external changes that need to be reflected in Select2 (such as changing the
+    value), you should trigger this event.
+  </p>
+
+{% highlight js linenos %}
+$('select').val('US'); // Select the option with a value of 'US'
+$('select').trigger('change'); // Notify any JS components that the value changed
+{% endhighlight %}
+
+  <h3>
+    Can I trigger an event other than <code>change</code> to notify Select2 of changes?
+  </h3>
+
+  <p>
+    It's common for other components to be listening to the <code>change</code>
+    event, or for custom event handlers to be attached that may have side
+    effects. Select2 does not have a custom event (like
+    <code>select2:update</code>) that can be triggered other than
+    <code>change</code>. You can rely on jQuery's event namespacing to limit
+    the scope to Select2 though by triggering the <code>change.select2</code>
+    event.
+  </p>
+
+{% highlight js linenos %}
+$('select').val('US'); // Change the value or make some change to the internal state
+$('select').trigger('change.select2'); // Notify only Select2 of changes
+{% endhighlight %}
 
   <h3>
     What events can be prevented? How can I prevent a selection from being made?