diff --git a/django_select2/forms.py b/django_select2/forms.py index 1c0c7059..96846038 100644 --- a/django_select2/forms.py +++ b/django_select2/forms.py @@ -7,36 +7,43 @@ library, hence these components are meant to be used with choice fields. -Widgets are generally of two types: - - 1. **Light** -- - They are not meant to be used when there - are too many options, say, in thousands. - This is because all those options would - have to be pre-rendered onto the page - and JavaScript would be used to search - through them. Said that, they are also one - the easiest to use. They are a - drop-in-replacement for Django's default - select widgets. - - 2(a). **Heavy** -- - They are suited for scenarios when the number of options - are large and need complex queries (from maybe different - sources) to get the options. - - This dynamic fetching of options undoubtedly requires - Ajax communication with the server. Django-Select2 includes - a helper JS file which is included automatically, - so you need not worry about writing any Ajax related JS code. - Although on the server side you do need to create a view - specifically to respond to the queries. - - 2(b). **Model** -- - Model-widgets are a further specialized versions of Heavies. - These do not require views to serve Ajax requests. - When they are instantiated, they register themselves - with one central view which handles Ajax requests for them. +Widgets are generally of tree types: +Light, Heavy and Model. + +Light +~~~~~ + +They are not meant to be used when there +are too many options, say, in thousands. +This is because all those options would +have to be pre-rendered onto the page +and JavaScript would be used to search +through them. Said that, they are also one +the easiest to use. They are a +drop-in-replacement for Django's default +select widgets. + +Heavy +~~~~~ + +They are suited for scenarios when the number of options +are large and need complex queries (from maybe different +sources) to get the options. + +This dynamic fetching of options undoubtedly requires +Ajax communication with the server. Django-Select2 includes +a helper JS file which is included automatically, +so you need not worry about writing any Ajax related JS code. +Although on the server side you do need to create a view +specifically to respond to the queries. + +Model +~~~~~ + +Model-widgets are a further specialized versions of Heavies. +These do not require views to serve Ajax requests. +When they are instantiated, they register themselves +with one central view which handles Ajax requests for them. Heavy and Model widgets have respectively the word 'Heavy' and 'Model' in their name. Light widgets are normally named, i.e. there is no 'Light' word diff --git a/docs/conf.py b/docs/conf.py index b339972f..845ceecd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,6 +31,7 @@ extensions = [ "sphinx.ext.autodoc", + "sphinx.ext.autosectionlabel", "sphinx.ext.napoleon", "sphinx.ext.inheritance_diagram", "sphinx.ext.intersphinx", diff --git a/docs/index.rst b/docs/index.rst index 35454f9c..0b2772ea 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,8 +32,9 @@ Add ``django_select`` to your URL root configuration: ] -``django-select2`` requires a cache backend which is **persistent** -across all application servers.. +The :ref:`Model` -widgets require a **persistent** cache backend across +all application servers. This is because the widget needs to store +meta data to be able to fetch the results based on the user input. **This means that the** :class:`.DummyCache` **backend will not work!**