Mark Lavin avatar Mark Lavin committed 144fe9a

Document chained selection example. fixes #19.

Comments (0)

Files changed (1)

docs/parameters.rst

 For the most part these event names should be self-explanatory. If you need additional
 detail you should refer to the `jQuery UI docs on these events <http://jqueryui.com/demos/autocomplete/#events>`_.
 
+
+Chained Selection Example
+--------------------------------------
+
+It's a fairly common pattern to have two or more inputs depend one another such City/State/Zip.
+In fact there are other Django apps dedicated to this purpose such as 
+`django-smart-selects <https://github.com/digi604/django-smart-selects>`_ or
+`django-ajax-filtered-fields <http://code.google.com/p/django-ajax-filtered-fields/>`_.
+It's possible to handle this kind of selection with django-selectable if you are willing
+to write a little javascript.
+
+Suppose we have city model
+
+    .. literalinclude:: ../example/core/models.py
+        :pyobject: City
+
+and a simple form
+
+    .. literalinclude:: ../example/core/forms.py
+        :pyobject: ChainedForm
+
+We want our users to select a city and if they choose a state then we will only
+show them cities in that state. To do this we will pass back chosen state as 
+addition parameter with the following javascript:
+
+    .. literalinclude:: ../example/core/templates/advanced.html
+        :start-after: {% block extra-js %}
+        :end-before: {% endblock %}
+
+
+Then in our lookup we will grab the state value and filter our results on it:
+
+    .. literalinclude:: ../example/core/lookups.py
+        :pyobject: CityLookup
+
+And that's it! We now have a working chained selection example. The full source
+is included in the example project.
+
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.