From 977c28c12904466a9f5fa1045dd9fd30a3a919ff Mon Sep 17 00:00:00 2001
From: David Neugebauer <david.neugebauer@posteo.de>
Date: Fri, 5 May 2023 15:48:18 +0200
Subject: [PATCH] Fix #128, add documentation on how to confifure select2
 options

---
 docs/django_select2.rst | 42 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 38 insertions(+), 4 deletions(-)

diff --git a/docs/django_select2.rst b/docs/django_select2.rst
index b726099a..512739b1 100644
--- a/docs/django_select2.rst
+++ b/docs/django_select2.rst
@@ -55,13 +55,47 @@ plugin.  It will handle both normal and heavy fields. Simply call
 
         $('.django-select2').djangoSelect2();
 
+Please replace all your ``.select2`` invocations with the here provided
+``.djangoSelect2``.
 
-You can pass see `Select2 options <https://select2.github.io/options.html>`_ if needed::
 
-        $('.django-select2').djangoSelect2({placeholder: 'Select an option'});
+Configuring Select2
+-------------------
+
+Select2 options can be configured either directly from Javascript or from within Django
+using widget attributes. `(List of options in the Select2 docs) <https://select2.org/configuration/options-api>`_.
+
+To pass options in javascript
+
+.. code-block:: javascript
+
+    $('.django-select2').djangoSelect2({
+        minimumInputLength: 0,
+        placeholder: 'Select an option',
+    });
+
+From Django, you can use ``data-`` attributes using the same names in camel-case and
+passing them to your widget. Select2 will then pick these up. For example when
+initialising a widget in a form, you could do:
+
+.. code-block:: python
+
+    class MyForm(forms.Form):
+        my_field = forms.ModelMultipleChoiceField(
+            widget=ModelSelect2MultipleWidget(
+                model=MyModel
+                search_fields=['another_field']
+                attrs={
+                    "data-minimum-input-length": 0,
+                    "data-placeholder": "Select an option",
+                    "data-close-on-select": "false",
+                }
+            )
+        )
+
+(If you do not want to initialize the widget, you could add the attributes by overriding
+a widget method and adding them in a super call, e.g. `get_context() <https://docs.djangoproject.com/en/dev/ref/forms/widgets/#django.forms.Widget.get_context>`_)
 
-Please replace all your ``.select2`` invocations with the here provided
-``.djangoSelect2``.
 
 Security & Authentication
 -------------------------