Add documentation for fields with choices

CHANGELOG.md

@@ -2,6 +2,25 @@
 
 These logs are also available on GitHub: https://github.com/pivotal-energy-solutions/django-datatable-view/releases
 
+## 0.9.0-beta.2
+Refinements since 0.9.0-beta.1
+
+#### New features
+
+It turns out I forgot to reintroduce some old functionality in the new modern column format code, but it's back!
+
+* Support for model fields that use ``choices``.  Specifically, we enable the user to search for the (case-insensitive) label of the various choices and the column will flip the search term to the right thing.  Fixed a bug in 0.8 choices support that made some assumptions that the choice db value was a string (using ``iexact`` too aggressively).
+* ``strptime`` date formatting will attempt to parse individual numbers and strings for matches that satisfy format symbols, such as ``%y`` (two digit year) and ``%M`` (month names).
+
+#### Fixes
+
+* Fixed a bug with legacy configuration where a sources list defined as a ``list`` instead of a ``tuple`` would cause dictionary key issues. [43ade82]
+* Fixed an issue with ``LegacyConfigurationDatatableView`` skipping the implicit processor discovery phase.  This will be removed in 1.0, but for 0.9 we will continue supporting implicit callbacks when the legacy view is in use. [88a0318]
+* Fixed a bug with columns declaring multiple sources that each targeted a value across an m2m relationship, where sources after the first would attempt to inspect the ORM path starting on the model where the first source left off during its own lookup. [4f0af04]
+* Fixed an issue with sending multiple column sources directly to the ``link_to_model`` helper, where the generated link text was a ``repr()`` of the source values list, instead of the default ``' '``-joined list of those values. [a27b6eb]
+* Changed choices label matching to support partial matches.
+* Changed choices label matching to allow multiple matches (since partial matching is now also allowed).  Previously there was a nuance that if two choices had the same label for whatever reason, it was undefined behavior which one would be selected to represent the database value in the converted search query.
+
 ## 0.9.0-beta.1
 This is a transition release to get people to 1.0, which brings a lot of syntax changes for table declaration on the python view, adopting a strategy that looks a lot like Django's forms framework,
 or django-rest-framework's serializers.

datatableview/tests/example_project/example_project/example_app/templates/base.html

@@ -86,6 +86,7 @@
                     <li class="nav-list-item dropdown-header">Advanced topics</li>
                     <li class="nav-list-item"><a href="{% url "per-request-options" %}">Per-request configuration</a></li>
                     <li class="nav-list-item"><a href="{% url "custom-model-fields" %}">Custom model fields</a></li>
+                    <li class="nav-list-item"><a href="{% url "choices-fields" %}">Fields with choices</a></li>
                     <li class="nav-list-item"><a href="{% url "multiple-tables" %}">Multiple tables on a page</a></li>
                     <li class="nav-list-item"><a href="{% url "embedded-table" %}">Embedded on another view</a></li>
                     <li class="nav-list-item"><a href="{% url "skipped-record" %}">Late record exclusion</a></li>

datatableview/tests/example_project/example_project/example_app/views.py

@@ -932,6 +932,52 @@ class Meta:
     implementation = u""""""
 
 
+class ChoicesFieldsDatatableView(DemoMixin, DatatableView):
+    """
+    Fields with choices are of course just normal model fields, so by default queries against the
+    column would be run for the database value part of the choice, not the label.
+
+    However, choice fields are automatically detected and if the user searches for a string which
+    happens to match a choice's label (case-insensitive), the column's search method will flip that
+    search term into the appropriate database value and run that search instead.
+
+    In the demo above, the raw ``status`` column ends up showing the raw value of course, but we've
+    added an extra column "Status Display" which draws on the automatic Django-supplied method
+    ``get_status_display()`` to show the label.
+
+    INFO:
+    Note that the ``status_display`` column we defined is not using a database-backed source, so
+    searches are not being run against it directly.  The reason a search for ``'published'`` matches
+    anything is because the ``status`` column is deciding that the search string can be found in one
+    of its labels.  Running a search for the raw value actually listed in the column is still a
+    valid query.
+    """
+    model = Entry
+    class datatable_class(Datatable):
+        status_display = columns.TextColumn("Status Display", 'get_status_display')
+
+        class Meta:
+            columns = ['id', 'headline', 'status', 'status_display']
+            labels = {
+                'status': "Status Value",
+            }
+
+    implementation = u"""
+    class MyDatatable(Datatable):
+        status_display = columns.TextColumn("Status Display", 'get_status_display')
+
+        class Meta:
+            columns = ['id', 'headline', 'status', 'status_display']
+            labels = {
+                'status': "Status Value",
+            }
+
+    class ChoicesFieldsDatatableView(DatatableView):
+        model = Entry
+        datatable_class = MyDatatable
+    """
+
+
 class MultipleTablesDatatableView(DemoMixin, MultipleDatatableView):
     """
     ``MultipleDatatableView`` uses a slightly different configuration mechanism to allow the view to