Merge pull request #1138 from pawl/fix_1130

improve column_filters documentation

examples/sqla-custom-filter/app.py

@@ -62,10 +62,9 @@ class UserAdmin(sqla.ModelView):
     # each filter in the list is a filter operation (equals, not equals, etc)
     # filters with the same name will appear as operations under the same filter
     column_filters = [
-        FilterEqual(User.last_name, 'Last Name'),
-        FilterLastNameBrown(
-            User.last_name, 'Last Name', options=(('1', 'Yes'), ('0', 'No'))
-        )
+        FilterEqual(column=User.last_name, name='Last Name'),
+        FilterLastNameBrown(column=User.last_name, name='Last Name',
+                            options=(('1', 'Yes'), ('0', 'No')))
     ]
 
 

flask_admin/contrib/mongoengine/view.py

@@ -53,9 +53,11 @@ class ModelView(BaseModelView):
         Collection of the column filters.
 
         Can contain either field names or instances of
-        :class:`flask_admin.contrib.mongoengine.filters.BaseFilter`
+        :class:`flask_admin.contrib.mongoengine.filters.BaseMongoEngineFilter`
         classes.
 
+        Filters will be grouped by name when displayed in the drop-down.
+
         For example::
 
             class MyModelView(BaseModelView):
@@ -63,8 +65,32 @@ class ModelView(BaseModelView):
 
         or::
 
+            from flask_admin.contrib.mongoengine.filters import BooleanEqualFilter
+
+            class MyModelView(BaseModelView):
+                column_filters = (BooleanEqualFilter(column=User.name, name='Name'),)
+
+        or::
+
+            from flask_admin.contrib.mongoengine.filters import BaseMongoEngineFilter
+
+            class FilterLastNameBrown(BaseMongoEngineFilter):
+                def apply(self, query, value):
+                    if value == '1':
+                        return query.filter(self.column == "Brown")
+                    else:
+                        return query.filter(self.column != "Brown")
+
+                def operation(self):
+                    return 'is Brown'
+
             class MyModelView(BaseModelView):
-                column_filters = (BooleanEqualFilter(User.name, 'Name'))
+                column_filters = [
+                    FilterLastNameBrown(
+                        column=User.last_name, name='Last Name',
+                        options=(('1', 'Yes'), ('0', 'No'))
+                    )
+                ]
     """
 
     model_form_converter = CustomModelConverter

flask_admin/contrib/peewee/view.py

@@ -27,7 +27,9 @@ class ModelView(BaseModelView):
         Collection of the column filters.
 
         Can contain either field names or instances of
-        :class:`flask_admin.contrib.peewee.filters.BaseFilter` classes.
+        :class:`flask_admin.contrib.peewee.filters.BasePeeweeFilter` classes.
+
+        Filters will be grouped by name when displayed in the drop-down.
 
         For example::
 
@@ -36,8 +38,32 @@ class ModelView(BaseModelView):
 
         or::
 
+            from flask_admin.contrib.peewee.filters import BooleanEqualFilter
+
+            class MyModelView(BaseModelView):
+                column_filters = (BooleanEqualFilter(column=User.name, name='Name'),)
+
+        or::
+
+            from flask_admin.contrib.peewee.filters import BasePeeweeFilter
+
+            class FilterLastNameBrown(BasePeeweeFilter):
+                def apply(self, query, value):
+                    if value == '1':
+                        return query.filter(self.column == "Brown")
+                    else:
+                        return query.filter(self.column != "Brown")
+
+                def operation(self):
+                    return 'is Brown'
+
             class MyModelView(BaseModelView):
-                column_filters = (BooleanEqualFilter(User.name, 'Name'))
+                column_filters = [
+                    FilterLastNameBrown(
+                        column=User.last_name, name='Last Name',
+                        options=(('1', 'Yes'), ('0', 'No'))
+                    )
+                ]
     """
 
     model_form_converter = CustomModelConverter

flask_admin/contrib/pymongo/view.py

@@ -29,13 +29,38 @@ class ModelView(BaseModelView):
         Collection of the column filters.
 
         Should contain instances of
-        :class:`flask_admin.contrib.pymongo.filters.BasePyMongoFilter`
-        classes.
+        :class:`flask_admin.contrib.pymongo.filters.BasePyMongoFilter` classes.
+
+        Filters will be grouped by name when displayed in the drop-down.
 
         For example::
 
+            from flask_admin.contrib.pymongo.filters import BooleanEqualFilter
+
+            class MyModelView(BaseModelView):
+                column_filters = (BooleanEqualFilter(column=User.name, name='Name'),)
+
+        or::
+
+            from flask_admin.contrib.pymongo.filters import BasePyMongoFilter
+
+            class FilterLastNameBrown(BasePyMongoFilter):
+                def apply(self, query, value):
+                    if value == '1':
+                        return query.filter(self.column == "Brown")
+                    else:
+                        return query.filter(self.column != "Brown")
+
+                def operation(self):
+                    return 'is Brown'
+
             class MyModelView(BaseModelView):
-                column_filters = (BooleanEqualFilter(User.name, 'Name'),)
+                column_filters = [
+                    FilterLastNameBrown(
+                        column=User.last_name, name='Last Name',
+                        options=(('1', 'Yes'), ('0', 'No'))
+                    )
+                ]
     """
 
     def __init__(self, coll,

flask_admin/contrib/sqla/view.py

@@ -117,7 +117,10 @@ class ModelView(BaseModelView):
     """
         Collection of the column filters.
 
-        Can contain either field names or instances of :class:`flask_admin.contrib.sqla.filters.BaseFilter` classes.
+        Can contain either field names or instances of
+        :class:`flask_admin.contrib.sqla.filters.BaseSQLAFilter` classes.
+
+        Filters will be grouped by name when displayed in the drop-down.
 
         For example::
 
@@ -126,8 +129,31 @@ class ModelView(BaseModelView):
 
         or::
 
+            from flask_admin.contrib.sqla.filters import BooleanEqualFilter
+
+            class MyModelView(BaseModelView):
+                column_filters = (BooleanEqualFilter(column=User.name, name='Name'),)
+
+        or::
+
+            from flask_admin.contrib.sqla.filters import BaseSQLAFilter
+
+            class FilterLastNameBrown(BaseSQLAFilter):
+                def apply(self, query, value, alias=None):
+                    if value == '1':
+                        return query.filter(self.column == "Brown")
+                    else:
+                        return query.filter(self.column != "Brown")
+
+                def operation(self):
+                    return 'is Brown'
+
             class MyModelView(BaseModelView):
-                column_filters = (BooleanEqualFilter(User.name, 'Name'))
+                column_filters = [
+                    FilterLastNameBrown(
+                        User.last_name, 'Last Name', options=(('1', 'Yes'), ('0', 'No'))
+                    )
+                ]
     """
 
     model_form_converter = form.AdminModelConverter