version 1.17.0

pigletto · pigletto · commit 7a1d025fb93f · 2018-09-04T21:08:42.000+02:00
diff --git a/CHANGES b/CHANGES
@@ -1,3 +1,8 @@
+2018.09.04 - 1.17.0
+ - If 'name' field is defined in columns definition (JS side) then it can be used to create 'columns' and
+   'order_columns' (see django-datatables-view-example for sample code).
+ - Added get_filter_method method to make it possible to easily change filter from istartswith to e.g. icontains.
+
 2018.04.17 - 1.16.0
  - removed exception handling - let exceptions propagate in a normal django flow (backward incompatible change!)
    Previously django_datatables_view has handled exceptions and returned these to datatables as JSON with status code
diff --git a/README.md b/README.md
@@ -23,17 +23,18 @@ _django_datatables_view_ uses **GenericViews**, so your view should just inherit
 (there is also a DatatableMixin - pure datatables handler that can be used with the mixins of your choice, eg. django-braces). These are:
 
   * **model** - the model that should be used to populate the datatable
-  * **columns** - the columns that are going to be displayed
-  * **order_columns** - list of column names used for sorting (eg. if user sorts by second column then second column name from this list will be used with order by clause).
-  * **filter_queryset** - if you want to filter your datatable then override this method
+  * **columns** - the columns that are going to be displayed. If not defined then django_datatables_view will look for 'name' in the columns definition provided in the request by DataTables, eg.: columnDefs: [{name: 'name', targets: [0]} (only works for datatables 1.10+)
+  * **order_columns** - list of column names used for sorting (eg. if user sorts by second column then second column name from this list will be used with order by clause). If not defined then django_datatables_view will look for 'name' in the columns definition provided in the request by DataTables, eg.: columnDefs: [{name: 'name', targets: [0]} (only works for datatables 1.10+)
+  * **filter_queryset** - if you want to filter your DataTable in some specific way then override this method. In case of older DataTables (pre 1.10) you need to override this method or there will be no filtering.
+  * **filter_method** - returns 'istartswith' by default, you can override it to use different filtering method, e.g. icontains: return self.FILTER_ICONTAINS
 
   For more advanced customisation you might want to override:
 
   * **get_initial_queryset** - method that should return queryset used to populate datatable
   * **prepare_results** - this method should return list of lists (rows with columns) as needed by datatables
   * **escape_values** - you can set this attribute to False in order to not escape values returned from render_column method
 
-The code is rather simple so do not hesitate to have a look at it. Method that is executed first (and that calls other methods) is **get_context_data**
+The code is rather simple so do not hesitate to have a look at it. Method that is executed first (and that calls other methods to execute whole logic) is **get_context_data**. Definitely have a look at this method!
 
 See example below:
   
@@ -71,12 +72,12 @@ See example below:
             # use parameters passed in GET request to filter queryset
 
             # simple example:
-            search = self.request.GET.get(u'search[value]', None)
+            search = self.request.GET.get('search[value]', None)
             if search:
                 qs = qs.filter(name__istartswith=search)
 
             # more advanced example using extra parameters
-            filter_customer = self.request.GET.get(u'customer', None)
+            filter_customer = self.request.GET.get('customer', None)
 
             if filter_customer:
                 customer_parts = filter_customer.split(' ')
@@ -133,12 +134,12 @@ class OrderListJson(BaseDatatableView):
         # use request parameters to filter queryset
 
         # simple example:
-        search = self.request.GET.get(u'search[value]', None)
+        search = self.request.GET.get('search[value]', None)
         if search:
             qs = qs.filter(name__istartswith=search)
 
         # more advanced example
-        filter_customer = self.request.GET.get(u'customer', None)
+        filter_customer = self.request.GET.get('customer', None)
 
         if filter_customer:
             customer_parts = filter_customer.split(' ')
@@ -162,4 +163,40 @@ class OrderListJson(BaseDatatableView):
                 item.modified.strftime("%Y-%m-%d %H:%M:%S")
             ])
         return json_data
-```
+```
+
+## Yet another example of views.py customisation ##
+
+This sample assumes that list of columns and order columns is defined on the client side (DataTables), eg.:
+
+```javascript
+$(document).ready(function() {
+    var dt_table = $('.datatable').dataTable({
+        order: [[ 0, "desc" ]],
+        columnDefs: [
+            {
+                name: 'name',
+                orderable: true,
+                searchable: true,
+                targets: [0]
+            },
+            {
+                name: 'description',
+                orderable: true,
+                searchable: true,
+                targets: [1]
+            }
+        ],
+        searching: true,
+        processing: true,
+        serverSide: true,
+        stateSave: true,
+        ajax: TESTMODEL_LIST_JSON_URL
+    });
+});
+```
+
+```python
+class TestModelListJson(BaseDatatableView):
+    model = TestModel
+```
diff --git a/README.rst b/README.rst
@@ -35,12 +35,24 @@ can be used with the mixins of your choice, eg. django-braces). These
 are:
 
 -  **model** - the model that should be used to populate the datatable
--  **columns** - the columns that are going to be displayed
+-  **columns** - the columns that are going to be displayed. If not
+   defined then django\_datatables\_view will look for 'name' in the
+   columns definition provided in the request by DataTables, eg.:
+   columnDefs: [{name: 'name', targets: [0]} (only works for datatables
+   1.10+)
 -  **order\_columns** - list of column names used for sorting (eg. if
    user sorts by second column then second column name from this list
-   will be used with order by clause).
--  **filter\_queryset** - if you want to filter your datatable then
-   override this method
+   will be used with order by clause). If not defined then
+   django\_datatables\_view will look for 'name' in the columns
+   definition provided in the request by DataTables, eg.: columnDefs:
+   [{name: 'name', targets: [0]} (only works for datatables 1.10+)
+-  **filter\_queryset** - if you want to filter your DataTable in some
+   specific way then override this method. In case of older DataTables
+   (pre 1.10) you need to override this method or there will be no
+   filtering.
+-  **filter\_method** - returns 'istartswith' by default, you can
+   override it to use different filtering method, e.g. icontains: return
+   self.FILTER\_ICONTAINS
 
 For more advanced customisation you might want to override:
 
@@ -52,8 +64,9 @@ For more advanced customisation you might want to override:
    not escape values returned from render\_column method
 
 The code is rather simple so do not hesitate to have a look at it.
-Method that is executed first (and that calls other methods) is
-**get\_context\_data**
+Method that is executed first (and that calls other methods to execute
+whole logic) is **get\_context\_data**. Definitely have a look at this
+method!
 
 See example below:
 
@@ -92,12 +105,12 @@ See example below:
                 # use parameters passed in GET request to filter queryset
 
                 # simple example:
-                search = self.request.GET.get(u'search[value]', None)
+                search = self.request.GET.get('search[value]', None)
                 if search:
                     qs = qs.filter(name__istartswith=search)
 
                 # more advanced example using extra parameters
-                filter_customer = self.request.GET.get(u'customer', None)
+                filter_customer = self.request.GET.get('customer', None)
 
                 if filter_customer:
                     customer_parts = filter_customer.split(' ')
@@ -156,12 +169,12 @@ Another example of views.py customisation
             # use request parameters to filter queryset
 
             # simple example:
-            search = self.request.GET.get(u'search[value]', None)
+            search = self.request.GET.get('search[value]', None)
             if search:
                 qs = qs.filter(name__istartswith=search)
 
             # more advanced example
-            filter_customer = self.request.GET.get(u'customer', None)
+            filter_customer = self.request.GET.get('customer', None)
 
             if filter_customer:
                 customer_parts = filter_customer.split(' ')
@@ -185,3 +198,41 @@ Another example of views.py customisation
                     item.modified.strftime("%Y-%m-%d %H:%M:%S")
                 ])
             return json_data
+
+Yet another example of views.py customisation
+---------------------------------------------
+
+This sample assumes that list of columns and order columns is defined on
+the client side (DataTables), eg.:
+
+.. code:: javascript
+
+    $(document).ready(function() {
+        var dt_table = $('.datatable').dataTable({
+            order: [[ 0, "desc" ]],
+            columnDefs: [
+                {
+                    name: 'name',
+                    orderable: true,
+                    searchable: true,
+                    targets: [0]
+                },
+                {
+                    name: 'description',
+                    orderable: true,
+                    searchable: true,
+                    targets: [1]
+                }
+            ],
+            searching: true,
+            processing: true,
+            serverSide: true,
+            stateSave: true,
+            ajax: TESTMODEL_LIST_JSON_URL
+        });
+    });
+
+.. code:: python
+
+    class TestModelListJson(BaseDatatableView):
+        model = TestModel
diff --git a/django_datatables_view/base_datatable_view.py b/django_datatables_view/base_datatable_view.py
@@ -14,32 +14,100 @@ class DatatableMixin(object):
     """
     model = None
     columns = []
+    _columns = []  # internal cache for columns definition
     order_columns = []
     max_display_length = 100  # max limit of records returned, do not allow to kill our server by huge sets of data
     pre_camel_case_notation = False  # datatables 1.10 changed query string parameter names
     none_string = ''
     escape_values = True  # if set to true then values returned by render_column will be escaped
-    
+    columns_data = []
+
+    FILTER_ISTARTSWITH = 'istartswith'
+    FILTER_ICONTAINS = 'icontains'
+
     @property
     def _querydict(self):
         if self.request.method == 'POST':
             return self.request.POST
         else:
             return self.request.GET
 
+    def get_filter_method(self):
+        """ Returns preferred filter method """
+        return self.FILTER_ISTARTSWITH
+
     def initialize(self, *args, **kwargs):
+        """ Determine which version of DataTables is being used - there are differences in parameters sent by
+            DataTables < 1.10.x
+        """
         if 'iSortingCols' in self._querydict:
             self.pre_camel_case_notation = True
 
     def get_order_columns(self):
-        """ Return list of columns used for ordering
+        """ Return list of columns used for ordering.
+            By default returns self.order_columns but if these are not defined it tries to get columns
+            from the request using the columns[i][name] attribute. This requires proper client side definition of
+            columns, eg:
+                columnDefs: [
+                    {
+                        name: 'username',
+                        orderable: true,
+                        targets: [0]
+                    },
+                    {
+                        name: 'email',
+                        orderable: false,
+                        targets: [1]
+                    }
+                ]
         """
-        return self.order_columns
+        if self.order_columns or self.pre_camel_case_notation:
+            return self.order_columns
+
+        # try to build list of order_columns using request data
+        order_columns = []
+        for column_def in self.columns_data:
+            if column_def['name']:
+                if column_def['orderable']:
+                    order_columns.append(column_def['name'])
+                else:
+                    order_columns.append('')
+            else:
+                # fallback to columns
+                order_columns = self._columns
+                break
+
+        self.order_columns = order_columns
+        return order_columns
 
     def get_columns(self):
-        """ Returns the list of columns that are returned in the result set
+        """ Returns the list of columns to be returned in the result set.
+            By default returns self.columns but if these are not defined it tries to get columns
+            from the request using the columns[i][name] attribute. This requires proper client side definition of
+            columns, eg:
+
+                columnDefs: [
+                    {
+                        name: 'username',
+                        targets: [0]
+                    },
+                    {
+                        name: 'email',
+                        targets: [1]
+                    }
+                ]
         """
-        return self.columns
+        if self.columns or self.pre_camel_case_notation:
+            return self.columns
+
+        columns = []
+        for column_def in self.columns_data:
+            if column_def['name']:
+                columns.append(column_def['name'])
+            else:
+                raise Exception('self.columns is not defined and there is no \'name\' defined in columns definition!')
+
+        return columns
 
     def render_column(self, row, column):
         """ Renders a column on a row. column can be given in a module notation eg. document.invoice.type
@@ -163,30 +231,33 @@ def extract_datatables_column_data(self):
         return col_data
 
     def filter_queryset(self, qs):
-        """ If search['value'] is provided then filter all searchable columns using istartswith
+        """ If search['value'] is provided then filter all searchable columns using filter_method (istartswith
+            by default).
+
+            Automatic filtering only works for Datatables 1.10+. For older versions override this method
         """
-        columns = self.get_columns()
+        columns = self._columns
         if not self.pre_camel_case_notation:
             # get global search value
             search = self._querydict.get('search[value]', None)
-            col_data = self.extract_datatables_column_data()
             q = Q()
-            for col_no, col in enumerate(col_data):
+            filter_method = self.get_filter_method()
+            for col_no, col in enumerate(self.columns_data):
                 # apply global search to all searchable columns
                 if search and col['searchable']:
-                    q |= Q(**{'{0}__istartswith'.format(columns[col_no].replace('.', '__')): search})
+                    q |= Q(**{'{0}__{1}'.format(columns[col_no].replace('.', '__'), filter_method): search})
 
                 # column specific filter
                 if col['search.value']:
                     qs = qs.filter(**{
-                        '{0}__istartswith'.format(columns[col_no].replace('.', '__')): col['search.value']})
+                        '{0}__{1}'.format(columns[col_no].replace('.', '__'), filter_method): col['search.value']})
             qs = qs.filter(q)
         return qs
 
     def prepare_results(self, qs):
         data = []
         for item in qs:
-            data.append([self.render_column(item, column) for column in self.get_columns()])
+            data.append([self.render_column(item, column) for column in self._columns])
         return data
 
     def handle_exception(self, e):
@@ -197,17 +268,28 @@ def get_context_data(self, *args, **kwargs):
         try:
             self.initialize(*args, **kwargs)
 
+            # prepare columns data (for DataTables 1.10+)
+            self.columns_data = self.extract_datatables_column_data()
+
+            # prepare list of columns to be returned
+            self._columns = self.get_columns()
+
+            # prepare initial queryset
             qs = self.get_initial_queryset()
 
-            # number of records before filtering
+            # store the total number of records (before filtering)
             total_records = qs.count()
 
+            # apply filters
             qs = self.filter_queryset(qs)
 
             # number of records after filtering
             total_display_records = qs.count()
 
+            # apply ordering
             qs = self.ordering(qs)
+
+            # apply pagintion
             qs = self.paging(qs)
 
             # prepare output data
diff --git a/setup.py b/setup.py
