Django Advanced Filters
=======================
+-----------+------------------+---------------------+----------+------------+
| Branch | Build | Coverage | PyPI | Gitter |
+===========+==================+=====================+==========+============+
| Master | |Build-Master| | |Coverage-Master| | |PyPI| | |Gitter| |
+-----------+------------------+---------------------+----------+------------+
| Develop | |Build-Develop| | |Coverage-Develop| | | |
+-----------+------------------+---------------------+----------+------------+
A django ModelAdmin mixin which adds advanced filtering abilities to the
admin.
Mimics the advanced search feature in
`VTiger <https://www.vtiger.com/>`__, `see here for more
info <https://www.vtiger.com/docs/creating-custom-filters>`__
.. figure:: https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/screenshot.png
:alt: Creating via a modal
:width: 768 px
For release notes, see `Changelog <https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/CHANGELOG.rst>`__
Requirements
============
- Django 2.2, >= 3.2 on Python 3.6+/PyPy3
- simplejson >= 3.6.5, < 4
Installation & Set up
=====================
1. Install from pypi: ``pip install django-advanced-filters``
2. Add ``'advanced_filters'`` to ``INSTALLED_APPS``.
3. Add ``url(r'^advanced_filters/', include('advanced_filters.urls'))``
to your project's urlconf.
4. Run ``python manage.py syncdb`` or ``python manage.py migrate`` (for django >= 1.7)
Integration Example
===================
Extending a ModelAdmin is pretty straightforward:
.. code-block:: python
from advanced_filters.admin import AdminAdvancedFiltersMixin
class ProfileAdmin(AdminAdvancedFiltersMixin, models.ModelAdmin):
list_filter = ('name', 'language', 'ts') # simple list filters
# specify which fields can be selected in the advanced filter
# creation form
advanced_filter_fields = (
'name',
'language',
'ts',
# even use related fields as lookup fields
'country__name',
'posts__title',
'comments__content',
)
Adding a new advanced filter (see below) will display a new list filter
named "Advanced filters" which will list all the filter the currently
logged in user is allowed to use (by default only those he/she created).
Custom naming of fields
-----------------------
Initially, each field in ``advanced_filter_fields`` is resolved into an
actual model field. That field's verbose\_name attribute is then used as
the text of the displayed option. While uncommon, it occasionally makes
sense to use a custom name, especially when following a relationship, as
the context then changes.
For example, when a profile admin allows filtering by a user name as
well as a sales representative name, it'll get confusing:
.. code-block:: python
class ProfileAdmin(AdminAdvancedFiltersMixin, models.ModelAdmin):
advanced_filter_fields = ('name', 'sales_rep__name')
In this case the field options will both be named "name" (by default).
To fix this, use custom naming:
.. code-block:: python
class ProfileAdmin(AdminAdvancedFiltersMixin, models.ModelAdmin):
advanced_filter_fields = ('name', ('sales_rep__name', 'assigned rep'))
Now, you will get two options, "name" and "assigned rep".
Adding new advanced filters
===========================
By default the mixin uses a template which extends django's built-in
``change_list`` template. This template is based off of grapelli's fork
of this template (hence the 'grp' classes and funny looking javascript).
The default template also uses the superb
`magnificPopup <dimsemenov/Magnific-Popup>`__ which is currently bundled
with the application.
Regardless of the above, you can easily write your own template which
uses context variables ``{{ advanced_filters }}`` and
``{{ advanced_filters.formset }}``, to render the advanced filter
creation form.
Structure
=========
Each advanced filter has only a couple of required fields when
constructed with the form; namely the title and a formset (consisting of
a form for each sub-query or rule of the filter query).
Each form in the formset requires the following fields: ``field``,
``operator``, ``value``
And allows the optional ``negate`` and ``remove`` fields.
Let us go over each of the fields in a rule fieldset.
Field
-----
The list of all available fields for this specific instance of the
ModelAdmin as specific by the ```advanced_filter_fields``
property. <#integration-example>`__
The OR field
~~~~~~~~~~~~
``OR`` is an additional field that is added to every rule's available
fields.
It allows constructing queries with `OR
statements <https://docs.djangoproject.com/en/dev/topics/db/queries/#complex-lookups-with-q-objects>`__.
You can use it by creating an "empty" rule with this field "between" a
set of 1 or more rules.
Operator
--------
Query field suffixes which specify how the ``WHERE`` query will be
constructed.
The currently supported are as follows: ``iexact``, ``icontains``,
``iregex``, ``range``, ``isnull``, ``istrue`` and ``isfalse``
For more detail on what they mean and how they function, see django's
`documentation on field
lookups <https://docs.djangoproject.com/en/dev/ref/models/querysets/#field-lookups>`__.
Value
-----
The value which the specific sub-query will be looking for, i.e the
value of the field specified above, or in django query syntax:
``.filter(field=value)``
Negate
------
A boolean (check-box) field to specify whether this rule is to be
negated, effectively making it a "exclude" sub-query.
Remove
------
Similarly to other `django
formsets <https://docs.djangoproject.com/en/dev/topics/forms/formsets/>`__,
used to remove the selected line on submit.
Editing previously created advanced filters
===========================================
The ``AdvancedFilterAdmin`` class (a subclass of ``ModelAdmin``) is
provided and registered with ``AdvancedFilter`` in admin.py module.
The model's change\_form template is overridden from grapelli's/django's
standard template, to mirror the add form modal as closely as possible.
*Note:* currently, adding new filters from the ModelAdmin change page is
not supported.
Query Serialization
===================
**TODO:** write a few words on how serialization of queries is done.
Model correlation
=================
Since version 1.0, ``AdvancedFilter`` are tightly coupled with a specific model
using the ``model`` field and the app\_label.Name template.
On creation, ``model`` is populated based on the admin changelist it's created
in.
This change has a few benefits:
1. The mixin can be used with multiple ``ModelAdmin`` classes while
performing specific query serialization and field validation that are
at the base of the filter functionality.
2. Users can edit previously created filters outside of the
context of a changelist, as we do in the
```AdvancedFilterAdmin`` <#editing-previously-created-advanced-filters>`__.
3. Limit the ``AdvancedListFilters`` to limit queryset (and thus, the
underlying options) to a specified model.
Views
=====
The GetFieldChoices view is required to dynamically (using javascript)
fetch a list of valid field choices when creating/changing an
``AdvancedFilter``.
TODO
====
- Add permission user/group selection functionality to the filter form
- Allow toggling of predefined templates (grappelli / vanilla django
admin), and front-end features.
- Support more (newer) python/django versions
.. |Build-Master| image:: https://travis-ci.org/modlinltd/django-advanced-filters.svg?branch=master
:target: https://travis-ci.org/modlinltd/django-advanced-filters
.. |Coverage-Master| image:: https://coveralls.io/repos/modlinltd/django-advanced-filters/badge.svg?branch=master
:target: https://coveralls.io/github/modlinltd/django-advanced-filters?branch=master
.. |PyPI| image:: https://img.shields.io/pypi/pyversions/django-advanced-filters.svg
:target: https://pypi.python.org/pypi/django-advanced-filters
.. |Gitter| image:: https://badges.gitter.im/Join%20Chat.svg
:target: https://gitter.im/modlinltd/django-advanced-filters?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
.. |Build-Develop| image:: https://travis-ci.org/modlinltd/django-advanced-filters.svg?branch=develop
:target: https://travis-ci.org/modlinltd/django-advanced-filters
.. |Coverage-Develop| image:: https://coveralls.io/repos/modlinltd/django-advanced-filters/badge.svg?branch=develop
:target: https://coveralls.io/github/modlinltd/django-advanced-filters?branch=develop
Changelog
=========
2.0.0 - Support Django 3.2 and 4.0
----------------------------------
**BREAKING CHANGE:** This release is the first 2.x release, and drops support for EOL python and Django versions, all feature development will be done against 2.X branch.**
Changes since 1.4.0:
Features
~~~~~~~~
- Add support for python 3.10 and Django 4.0 (Merge 7bfb5b6)
- Add compiled IT translation (Merge e39395f)
Bug fixes
~~~~~~~~~
- Don't add empty form to AdvancedFilterFormSet.forms (Merge 7bfb5b6)
Other
~~~~~
- Drop support for EOL Python 2.7 and 3.5 (Merge dfeb005)
- Drop support for EOL Django 3.0 (Merge dfeb005)
- Drop support for EOL Django up to 2.2 (Merge dfeb005)
- Upgrade Python syntax with pyupgrade --py36-plus (Merge dfeb005)
- Remove six (Merge dfeb005)
- Remove unused import (Merge dfeb005)
- Drop support for python 3.6 (Merge 7bfb5b6)
- Correct support matrix (Merge 7bfb5b6)
- Simplify url path import (Merge 7bfb5b6)
- Remove standalone clean env from tox envlist (Merge 7bfb5b6)
- Remove unused cached_property import (Merge 7bfb5b6)
- Add Django 3.2 to classifiers (#163)
- f-string for model_name string interpolation (Merge dfeb005)
- remove unsupported django 3.1 from tox matrix (Merge 7bfb5b6)
- update README and remove Django 3.1 classifier
Contributors
~~~~~~~~~~~~
- Fabrizio Corallini
- Dmytro Litvinov
- Hugo van Kemenade
- Pavel Savchenko
1.4.0 - Latvian translation and minor fixes
-------------------------------------------
**NOTE: This release will be the last one to include features in 1.X branch, other than urgent hotfixes; version 2.X will drop support for EOL python and Django versions, and all future development will be done against 2.X branch**
Changes since 1.3.0:
Features
~~~~~~~~
- Add Latvian translation (#135)
- Commit compiled translation files (Merge db448fa)
Bug fixes
~~~~~~~~~
- switch from ugettext to gettext (#134)
- don't use default dict (Merge db448fa)
- correctly update extra_context (Merge db448fa)
- support parallel coverage reporting (Merge db448fa)
Other
~~~~~
- Fix CI for 2021 (#147)
- Don't run tests in GitHub actions twice, one per PR is enough (da6fe7f24982a0fa69fcebff79d658b087de5e5b)
- Ignore vscode settings (Merge db448fa)
Contributors
~~~~~~~~~~~~
- Pavel Savchenko
- Māris Nartišs
1.3.0 - Django 3.1 and more
---------------------------
Apologies for the late release, and thanks to everyone that contributed.
Bug fixes
~~~~~~~~~
- Add support for python 3.9 and django 3.1
- import FieldDoesNotExist from django.core.exceptions
Misc
~~~~
- Update django-braces
- Update Admin to show model
- Add Turkish translation
- Correct travis.yml deprecated/dupe keywords
Contributors
~~~~~~~~~~~~
- Pavel Savchenko
- predatell
- Özcan YARIMDÜNYA
- Thu Trang Pham
- João Batista
1.2.0 - Django 3 and more
-------------------------
It's finally time to drop the dirty old rags and don some fresh colors.
Thanks to effort from multiple contributors, this version includes support
for newest Django version.
Breaking Changes
~~~~~~~~~~~~~~~~
* Add support for Django 2.2 and 3.0
* Drop support for Django < 1.9
* Drop support for Python 3.3-3.4
*django-advanced-filters now support only* **python 2.7, and 3.5 - 3.8.**
Features
~~~~~~~~
- Switch deprecated force_text to force_str (Merge 0427d11)
Bug fixes
~~~~~~~~~
- Avoid installing newer braces (Merge 0427d11)
- Allow choices sort on None fields (Merge 142ecd0)
Docs / Tests
~~~~~~~~~~~~
- Update dependencies stated in the README
- Refactor some unittest test cases into pytest (Merge 41271b7)
- Test the CleanWhiteSpacesMixin helper
Misc
~~~~
- Update requirements for new test deps matrix (Merge 0427d11)
- Replace deprecated assertEquals (Merge 41271b7)
- Replace deprecated logger.warn with warning (Merge 41271b7)
- Bump test dependencies (Merge 41271b7)
- Update python and add Django classifiers
Contributors
~~~~~~~~~~~~
- Petr Dlouhý
- Alon Raizman
- Hugo Maingonnat
- Arpit
- Pavel Savchenko
1.1.1 - CHANGELOG rendering is hard
-----------------------------------
This release is for fixing the bug when installing with specific environment (
locale that defaults to CP-1252).
Bug fixes
~~~~~~~~~
- Add encoding='utf-8' to open() in setup.py (Merge 2fe81aa)
Docs / Other
~~~~~~~~~~~~
- add CONTRIBUTING.rst with common processes (Merge ee7907e)
- Update issue templates (Merge ee7907e)
Contributors
~~~~~~~~~~~~
- Rebecca Turner
- Pavel Savchenko
1.1.0 - The future is bright
----------------------------
This release highlights support for Django 2.0 and 2.1 as well as
deprecating support for versions Django < 1.7 and Python 2.6 and 3.3
Bug fixes
~~~~~~~~~
- bump django-braces==1.13 for Django 2 support (Merge 80e055e)
- use request context processor in test_project (Merge 80e055e)
Misc.
~~~~~
- ignore .DS_Store
- fixes for Django 2.0 and 1.11, update tests (Merge 80e055e)
- test in Django 2.1 (Merge d8d236d)
- add updated migrations of model attributes (Merge 80e055e)
- fix ValueError while creating empty form (Merge d8d236d)
- python 2.6 and django < 1.7 are deprecated
- lower and upper bounds in install_requires
- avoid all-catch except clause (Merge 80e055e)
Tests
~~~~~
- correct tox env django spec for ver 1.11 (Merge 80e055e)
- correct make_query assertion for Django>=2 (Merge 80e055e)
- update pytest-django in diff. envs + tox (Merge d8d236d)
Contributors
~~~~~~~~~~~~
- Goncalo Gomes
- predatell
- Petr Dlouhý
- benny daon
- Pavel Savchenko
1.0.7.1 - Fix PyPi fail
-----------------------
- Equivalent to the prev version, bumped since we can't reupload the files to PyPi.
1.0.7 - The holiday edition
---------------------------
This is mostly a minor release with the biggest being the `AdvancedFilterForm.Media` fix, 2 additional translations and bunch of docs cleanup (thanks everyone)!
Changes since 1.0.6:
Bug Fixes
~~~~~~~~~
- Fix AdvancedFilterForm Media declaration
- Fix pep8: E128 on forms.py (Merge d7acb36)
Features
~~~~~~~~
- Add Japanese locale (Merge d7acb36)
- Add Spanish locale (Merge 1a482cf)
Documentation:
~~~~~~~~~~~~~~
- a bit of polishing (Merge 4c88ea3)
- removing confusing migrations paragraph (Merge 4c88ea3)
Contributors:
~~~~~~~~~~~~~
- KINOSHITA Shinji
- Pavel Savchenko
- Benny Daon
- Mathieu Richardoz
- José Sánchez Moreno
1.0.6 - Bout Time
-----------------
This release is long overdue, and includes some important fixes as well as general improvements to code and documentation.
Bug Fixes
~~~~~~~~~
- fixing TypeError: can only concatenate tuple (not "list") to tuple
- ensure select2 is included last (Merge 9831ba5)
- add script to load jQuery globally
- remove invalid template variables
- fix input focusing error in chrome
- fix error when one missing range parameter caused error + test (Merge 365b646)
Features
~~~~~~~~
- don't override original change_list_templates in AdminAdvancedFiltersMixin
- make date range placeholder more pleasant (Merge 365b646)
- add created_at field
- Russian locale provided
Documentation
~~~~~~~~~~~~~
- make it clear easy-select2 is not required anymore (Merge 9831ba5)
- Clarify how to import AdminAdvancedFiltersMixin in README
Tests
~~~~~
- add more fields/filter to test ModelAdmin
Contributors
~~~~~~~~~~~~
- Grigoriy Beziuk
- Никита Конин
- Pavel Savchenko
- Yuval Adam
- Petr Dlouhý
1.0.5 - Compatibility bump
--------------------------
Bugs
~~~~
- updated AdvancedFilterQueryForm to include numeric comparison operators (Merge d3ee9f4)
- Fixed a bug where editing an existing Advanced Filter defaulted all operators to 'Equals' (Merge d3ee9f4)
- set AFQFormSet extra=0 instead of extra=1. I did this because having to check Delete is not clear to end users. (Merge d3ee9f4)
- changed the Advanced Filter admin so you a User by default can only view/edit filters that they create (unless they are a superuser) (Merge d3ee9f4)
- Fixed failing tests. Fixed bug where users weren't properly getting permissions to change or delete their filters (Merge d3ee9f4)
- changed solution for extra form appearing on editing. Now initialize form checks for falsy value for extra rather than extra just being None (Merge d3ee9f4)
- removed 'not instance from requirements for no extras (Merge d3ee9f4)
- pep8 fix (Merge d3ee9f4)
- Fixed labeling error with 'Greater Than or Equal To' (Merge d3ee9f4)
- Changes URL declaration to avoid deprecated pattern
- select2 only initializes if there are choices available. otherwise, the standard text input will be used (Merge 35d7063)
- Revert "select2 only initializes if there are choices available. otherwise, the standard text input will be used" (Merge 35d7063)
- updated query for choices for select2 field so that it will take only distinct choices. This allows max_choices to be the maximum unique choices. (Merge 35d7063)
- Changes URL declaration to avoid deprecated pattern (Merge 35d7063)
- refactored retrieval of choices so that the db is getting distinct values; added test (Merge 35d7063)
- pep8 (Merge 35d7063)
- Use order_by to avoid ambiguity
- drop django-easy-select2 and include select2 directly
Tests
~~~~~
- test with both Python 3.5 and Django 1.10
- removed print statement from test (Merge 35d7063)
- fixed failing test to account for new distinct for max choices (Merge 35d7063)
- added test to make sure all operators are properly restored from Queries (Merge d3ee9f4)
Contributors
~~~~~~~~~~~~
- Pavel Savchenko
- PJ Passalacqua
- Hermano Cabral
1.0.4 - Unbreak Python 3
------------------------
This release contains a fix to allow distribution installation on Python 3 which was broken since 1.0.2
1.0.3 - The Package Fix
-----------------------
This is a quick fix for packaging (setup.py) errors and documentation.
Bugs
~~~~
- add missing Django 1.7 migrations
- README updated to mention ``manage.py migrate`` command
- Use ReST for README and CHANGELOG: avoid conversion from markdown
1.0.2 - A Better Future
-----------------------
This release features better test coverage and support for Django 1.9.
Bugs
~~~~
- stretch formset table to the modal container width
- toggle advanced ``vendor/jquery`` dir according to Django version
- retain support older Django versions
- clean up legacy tags in templates
Tests
~~~~~
- add admin views tests
- add Django 1.9 to test matrix
- other minor improvements
Docs
~~~~
- Improve README with a newer screenshot and pretty tables for badges
Contributors:
~~~~~~~~~~~~~
- Pavel Savchenko
- Leonardo J. Caballero G
- Schuyler Duveen
1.0.1 - A Public Release
------------------------
Bugs
~~~~
- proper support for py26 and py3X and different Django releases
- avoid querying all instances for choices
- resolve settings inside view and refine error handling
Tests
~~~~~
- add doctests to the ``form_helpers``
- add tests for ``forms``
- add test case ``views.TestGetFieldChoicesView``
- setup.py/travis: add ``test-reqs.txt`` as extras\_require
- refactor testing to use ``py.test`` and run ``tox`` from ``setup.py``
- travis: use latest version of each Django release
Docs:
~~~~~
- ``README``: explain what we test against
1.0 - First contact
-------------------
Major changes
~~~~~~~~~~~~~
- Add a new (required) field
```AdvancedFilter.model`` <https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/README.rst#model-correlation>`__
- Add parsing query dict into initialized formsets (allows for `editing
existing
instance <https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/README.rst#editing-previously-created-advanced-filters>`__).
- Add
```AdvancedFilterAdmin`` <#editing-previously-created-advanced-filters>`__
for actually accessing and `editing existing ``AdvancedFilter``
instances <https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/README.rst#editing-previously-created-advanced-filters>`__.
- Use `Select2 <https://github.com/asyncee/django-easy-select2>`__ and
an AJAX view to dynamically populate ```field``
options <https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/README.rst#fields>`__.
- Add proper support for nested serialization of queries.
Minor changes
~~~~~~~~~~~~~
- Implement more ```operators`` <https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/README.rst#operators>`__ (``isnull``,
``istrue`` and ``isfalse``)
- Allow `custom verbose naming of fields in
advanced\_filter\_fields <https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/README.rst#custom-naming-of-fields>`__
- Add helper methods to the model to hide (and decouple) core
serialization functionality from users.
- Strip whitespace in field values validation
- Setup and packaging (``setup.py``/``MANIFEST.in``)
- Hide ``QSerializer`` calling logic in the model
- Allow modifying ``advanced_filter_form`` property (defaults to
``AdvancedFilterForm``)
- Correct documentation regarding position of mixin in subclass (issue
#1)
Raw data
{
"_id": null,
"home_page": "https://github.com/modlinltd/django-advanced-filters",
"name": "django-advanced-filters",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "django-admin admin advanced filters custom query",
"author": "Pavel Savchenko",
"author_email": "pavel@modlinltd.com",
"download_url": "https://files.pythonhosted.org/packages/eb/a5/47d761549782124270e97079c7920bec0ef6ae38e6ec47f612df3d87c7e8/django-advanced-filters-2.0.0.tar.gz",
"platform": null,
"description": "Django Advanced Filters\n=======================\n\n+-----------+------------------+---------------------+----------+------------+\n| Branch | Build | Coverage | PyPI | Gitter |\n+===========+==================+=====================+==========+============+\n| Master | |Build-Master| | |Coverage-Master| | |PyPI| | |Gitter| |\n+-----------+------------------+---------------------+----------+------------+\n| Develop | |Build-Develop| | |Coverage-Develop| | | |\n+-----------+------------------+---------------------+----------+------------+\n\nA django ModelAdmin mixin which adds advanced filtering abilities to the\nadmin.\n\nMimics the advanced search feature in\n`VTiger <https://www.vtiger.com/>`__, `see here for more\ninfo <https://www.vtiger.com/docs/creating-custom-filters>`__\n\n.. figure:: https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/screenshot.png\n :alt: Creating via a modal\n :width: 768 px\n\n\nFor release notes, see `Changelog <https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/CHANGELOG.rst>`__\n\nRequirements\n============\n\n- Django 2.2, >= 3.2 on Python 3.6+/PyPy3\n- simplejson >= 3.6.5, < 4\n\n\nInstallation & Set up\n=====================\n\n1. Install from pypi: ``pip install django-advanced-filters``\n2. Add ``'advanced_filters'`` to ``INSTALLED_APPS``.\n3. Add ``url(r'^advanced_filters/', include('advanced_filters.urls'))``\n to your project's urlconf.\n4. Run ``python manage.py syncdb`` or ``python manage.py migrate`` (for django >= 1.7)\n\nIntegration Example\n===================\n\nExtending a ModelAdmin is pretty straightforward:\n\n.. code-block:: python\n\n from advanced_filters.admin import AdminAdvancedFiltersMixin\n\n class ProfileAdmin(AdminAdvancedFiltersMixin, models.ModelAdmin):\n list_filter = ('name', 'language', 'ts') # simple list filters\n\n # specify which fields can be selected in the advanced filter\n # creation form\n advanced_filter_fields = (\n 'name',\n 'language',\n 'ts',\n\n # even use related fields as lookup fields\n 'country__name',\n 'posts__title',\n 'comments__content',\n )\n\nAdding a new advanced filter (see below) will display a new list filter\nnamed \"Advanced filters\" which will list all the filter the currently\nlogged in user is allowed to use (by default only those he/she created).\n\nCustom naming of fields\n-----------------------\n\nInitially, each field in ``advanced_filter_fields`` is resolved into an\nactual model field. That field's verbose\\_name attribute is then used as\nthe text of the displayed option. While uncommon, it occasionally makes\nsense to use a custom name, especially when following a relationship, as\nthe context then changes.\n\nFor example, when a profile admin allows filtering by a user name as\nwell as a sales representative name, it'll get confusing:\n\n.. code-block:: python\n\n class ProfileAdmin(AdminAdvancedFiltersMixin, models.ModelAdmin):\n advanced_filter_fields = ('name', 'sales_rep__name')\n\nIn this case the field options will both be named \"name\" (by default).\n\nTo fix this, use custom naming:\n\n.. code-block:: python\n\n class ProfileAdmin(AdminAdvancedFiltersMixin, models.ModelAdmin):\n advanced_filter_fields = ('name', ('sales_rep__name', 'assigned rep'))\n\nNow, you will get two options, \"name\" and \"assigned rep\".\n\nAdding new advanced filters\n===========================\n\nBy default the mixin uses a template which extends django's built-in\n``change_list`` template. This template is based off of grapelli's fork\nof this template (hence the 'grp' classes and funny looking javascript).\n\nThe default template also uses the superb\n`magnificPopup <dimsemenov/Magnific-Popup>`__ which is currently bundled\nwith the application.\n\nRegardless of the above, you can easily write your own template which\nuses context variables ``{{ advanced_filters }}`` and\n``{{ advanced_filters.formset }}``, to render the advanced filter\ncreation form.\n\nStructure\n=========\n\nEach advanced filter has only a couple of required fields when\nconstructed with the form; namely the title and a formset (consisting of\na form for each sub-query or rule of the filter query).\n\nEach form in the formset requires the following fields: ``field``,\n``operator``, ``value``\n\nAnd allows the optional ``negate`` and ``remove`` fields.\n\nLet us go over each of the fields in a rule fieldset.\n\nField\n-----\n\nThe list of all available fields for this specific instance of the\nModelAdmin as specific by the ```advanced_filter_fields``\nproperty. <#integration-example>`__\n\nThe OR field\n~~~~~~~~~~~~\n\n``OR`` is an additional field that is added to every rule's available\nfields.\n\nIt allows constructing queries with `OR\nstatements <https://docs.djangoproject.com/en/dev/topics/db/queries/#complex-lookups-with-q-objects>`__.\nYou can use it by creating an \"empty\" rule with this field \"between\" a\nset of 1 or more rules.\n\nOperator\n--------\n\nQuery field suffixes which specify how the ``WHERE`` query will be\nconstructed.\n\nThe currently supported are as follows: ``iexact``, ``icontains``,\n``iregex``, ``range``, ``isnull``, ``istrue`` and ``isfalse``\n\nFor more detail on what they mean and how they function, see django's\n`documentation on field\nlookups <https://docs.djangoproject.com/en/dev/ref/models/querysets/#field-lookups>`__.\n\nValue\n-----\n\nThe value which the specific sub-query will be looking for, i.e the\nvalue of the field specified above, or in django query syntax:\n``.filter(field=value)``\n\nNegate\n------\n\nA boolean (check-box) field to specify whether this rule is to be\nnegated, effectively making it a \"exclude\" sub-query.\n\nRemove\n------\n\nSimilarly to other `django\nformsets <https://docs.djangoproject.com/en/dev/topics/forms/formsets/>`__,\nused to remove the selected line on submit.\n\nEditing previously created advanced filters\n===========================================\n\nThe ``AdvancedFilterAdmin`` class (a subclass of ``ModelAdmin``) is\nprovided and registered with ``AdvancedFilter`` in admin.py module.\n\nThe model's change\\_form template is overridden from grapelli's/django's\nstandard template, to mirror the add form modal as closely as possible.\n\n*Note:* currently, adding new filters from the ModelAdmin change page is\nnot supported.\n\nQuery Serialization\n===================\n\n**TODO:** write a few words on how serialization of queries is done.\n\nModel correlation\n=================\n\nSince version 1.0, ``AdvancedFilter`` are tightly coupled with a specific model\nusing the ``model`` field and the app\\_label.Name template.\nOn creation, ``model`` is populated based on the admin changelist it's created\nin.\n\nThis change has a few benefits:\n\n1. The mixin can be used with multiple ``ModelAdmin`` classes while\n performing specific query serialization and field validation that are\n at the base of the filter functionality.\n\n2. Users can edit previously created filters outside of the\n context of a changelist, as we do in the\n ```AdvancedFilterAdmin`` <#editing-previously-created-advanced-filters>`__.\n\n3. Limit the ``AdvancedListFilters`` to limit queryset (and thus, the\n underlying options) to a specified model.\n\nViews\n=====\n\nThe GetFieldChoices view is required to dynamically (using javascript)\nfetch a list of valid field choices when creating/changing an\n``AdvancedFilter``.\n\nTODO\n====\n\n- Add permission user/group selection functionality to the filter form\n- Allow toggling of predefined templates (grappelli / vanilla django\n admin), and front-end features.\n- Support more (newer) python/django versions\n\n.. |Build-Master| image:: https://travis-ci.org/modlinltd/django-advanced-filters.svg?branch=master\n :target: https://travis-ci.org/modlinltd/django-advanced-filters\n.. |Coverage-Master| image:: https://coveralls.io/repos/modlinltd/django-advanced-filters/badge.svg?branch=master\n :target: https://coveralls.io/github/modlinltd/django-advanced-filters?branch=master\n.. |PyPI| image:: https://img.shields.io/pypi/pyversions/django-advanced-filters.svg\n :target: https://pypi.python.org/pypi/django-advanced-filters\n.. |Gitter| image:: https://badges.gitter.im/Join%20Chat.svg\n :target: https://gitter.im/modlinltd/django-advanced-filters?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge\n.. |Build-Develop| image:: https://travis-ci.org/modlinltd/django-advanced-filters.svg?branch=develop\n :target: https://travis-ci.org/modlinltd/django-advanced-filters\n.. |Coverage-Develop| image:: https://coveralls.io/repos/modlinltd/django-advanced-filters/badge.svg?branch=develop\n :target: https://coveralls.io/github/modlinltd/django-advanced-filters?branch=develop\n\nChangelog\n=========\n\n2.0.0 - Support Django 3.2 and 4.0\n----------------------------------\n\n**BREAKING CHANGE:** This release is the first 2.x release, and drops support for EOL python and Django versions, all feature development will be done against 2.X branch.**\n\nChanges since 1.4.0:\n\nFeatures\n~~~~~~~~\n\n- Add support for python 3.10 and Django 4.0 (Merge 7bfb5b6)\n- Add compiled IT translation (Merge e39395f)\n\nBug fixes\n~~~~~~~~~\n\n- Don't add empty form to AdvancedFilterFormSet.forms (Merge 7bfb5b6)\n\nOther\n~~~~~\n\n- Drop support for EOL Python 2.7 and 3.5 (Merge dfeb005)\n- Drop support for EOL Django 3.0 (Merge dfeb005)\n- Drop support for EOL Django up to 2.2 (Merge dfeb005)\n- Upgrade Python syntax with pyupgrade --py36-plus (Merge dfeb005)\n- Remove six (Merge dfeb005)\n- Remove unused import (Merge dfeb005)\n- Drop support for python 3.6 (Merge 7bfb5b6)\n- Correct support matrix (Merge 7bfb5b6)\n- Simplify url path import (Merge 7bfb5b6)\n- Remove standalone clean env from tox envlist (Merge 7bfb5b6)\n- Remove unused cached_property import (Merge 7bfb5b6)\n- Add Django 3.2 to classifiers (#163)\n- f-string for model_name string interpolation (Merge dfeb005)\n- remove unsupported django 3.1 from tox matrix (Merge 7bfb5b6)\n- update README and remove Django 3.1 classifier\n\nContributors\n~~~~~~~~~~~~\n\n- Fabrizio Corallini\n- Dmytro Litvinov\n- Hugo van Kemenade\n- Pavel Savchenko\n\n1.4.0 - Latvian translation and minor fixes\n-------------------------------------------\n\n**NOTE: This release will be the last one to include features in 1.X branch, other than urgent hotfixes; version 2.X will drop support for EOL python and Django versions, and all future development will be done against 2.X branch**\n\nChanges since 1.3.0:\n\nFeatures\n~~~~~~~~\n\n- Add Latvian translation (#135)\n- Commit compiled translation files (Merge db448fa)\n\nBug fixes\n~~~~~~~~~\n\n- switch from ugettext to gettext (#134)\n- don't use default dict (Merge db448fa)\n- correctly update extra_context (Merge db448fa)\n- support parallel coverage reporting (Merge db448fa)\n\nOther\n~~~~~\n\n- Fix CI for 2021 (#147)\n- Don't run tests in GitHub actions twice, one per PR is enough (da6fe7f24982a0fa69fcebff79d658b087de5e5b)\n- Ignore vscode settings (Merge db448fa)\n\nContributors\n~~~~~~~~~~~~\n\n- Pavel Savchenko\n- M\u0101ris Narti\u0161s\n\n\n1.3.0 - Django 3.1 and more\n---------------------------\n\nApologies for the late release, and thanks to everyone that contributed.\n\nBug fixes\n~~~~~~~~~\n\n- Add support for python 3.9 and django 3.1\n- import FieldDoesNotExist from django.core.exceptions\n\nMisc\n~~~~\n\n- Update django-braces\n- Update Admin to show model\n- Add Turkish translation\n- Correct travis.yml deprecated/dupe keywords\n\nContributors\n~~~~~~~~~~~~\n\n- Pavel Savchenko\n- predatell\n- \u00d6zcan YARIMD\u00dcNYA\n- Thu Trang Pham\n- Jo\u00e3o Batista\n\n\n1.2.0 - Django 3 and more\n-------------------------\n\nIt's finally time to drop the dirty old rags and don some fresh colors.\n\nThanks to effort from multiple contributors, this version includes support\nfor newest Django version.\n\nBreaking Changes\n~~~~~~~~~~~~~~~~\n\n* Add support for Django 2.2 and 3.0\n* Drop support for Django < 1.9\n* Drop support for Python 3.3-3.4\n\n*django-advanced-filters now support only* **python 2.7, and 3.5 - 3.8.**\n\nFeatures\n~~~~~~~~\n\n- Switch deprecated force_text to force_str (Merge 0427d11)\n\nBug fixes\n~~~~~~~~~\n\n- Avoid installing newer braces (Merge 0427d11)\n- Allow choices sort on None fields (Merge 142ecd0)\n\nDocs / Tests\n~~~~~~~~~~~~\n\n- Update dependencies stated in the README\n- Refactor some unittest test cases into pytest (Merge 41271b7)\n- Test the CleanWhiteSpacesMixin helper\n\nMisc\n~~~~\n\n- Update requirements for new test deps matrix (Merge 0427d11)\n- Replace deprecated assertEquals (Merge 41271b7)\n- Replace deprecated logger.warn with warning (Merge 41271b7)\n- Bump test dependencies (Merge 41271b7)\n- Update python and add Django classifiers\n\n\nContributors\n~~~~~~~~~~~~\n\n- Petr Dlouh\u00fd\n- Alon Raizman\n- Hugo Maingonnat\n- Arpit\n- Pavel Savchenko\n\n\n1.1.1 - CHANGELOG rendering is hard\n-----------------------------------\n\nThis release is for fixing the bug when installing with specific environment (\nlocale that defaults to CP-1252).\n\nBug fixes\n~~~~~~~~~\n\n- Add encoding='utf-8' to open() in setup.py (Merge 2fe81aa)\n\nDocs / Other\n~~~~~~~~~~~~\n\n- add CONTRIBUTING.rst with common processes (Merge ee7907e)\n- Update issue templates (Merge ee7907e)\n\nContributors\n~~~~~~~~~~~~\n\n- Rebecca Turner\n- Pavel Savchenko\n\n\n1.1.0 - The future is bright\n----------------------------\n\nThis release highlights support for Django 2.0 and 2.1 as well as\ndeprecating support for versions Django < 1.7 and Python 2.6 and 3.3\n\nBug fixes\n~~~~~~~~~\n\n- bump django-braces==1.13 for Django 2 support (Merge 80e055e)\n- use request context processor in test_project (Merge 80e055e)\n\nMisc.\n~~~~~\n\n- ignore .DS_Store\n- fixes for Django 2.0 and 1.11, update tests (Merge 80e055e)\n- test in Django 2.1 (Merge d8d236d)\n- add updated migrations of model attributes (Merge 80e055e)\n- fix ValueError while creating empty form (Merge d8d236d)\n- python 2.6 and django < 1.7 are deprecated\n- lower and upper bounds in install_requires\n- avoid all-catch except clause (Merge 80e055e)\n\nTests\n~~~~~\n\n- correct tox env django spec for ver 1.11 (Merge 80e055e)\n- correct make_query assertion for Django>=2 (Merge 80e055e)\n- update pytest-django in diff. envs + tox (Merge d8d236d)\n\nContributors\n~~~~~~~~~~~~\n\n- Goncalo Gomes\n- predatell\n- Petr Dlouh\u00fd\n- benny daon\n- Pavel Savchenko\n\n\n1.0.7.1 - Fix PyPi fail\n-----------------------\n\n- Equivalent to the prev version, bumped since we can't reupload the files to PyPi.\n\n1.0.7 - The holiday edition\n---------------------------\n\nThis is mostly a minor release with the biggest being the `AdvancedFilterForm.Media` fix, 2 additional translations and bunch of docs cleanup (thanks everyone)!\n\nChanges since 1.0.6:\n\nBug Fixes\n~~~~~~~~~\n\n- Fix AdvancedFilterForm Media declaration\n- Fix pep8: E128 on forms.py (Merge d7acb36)\n\nFeatures\n~~~~~~~~\n\n- Add Japanese locale (Merge d7acb36)\n- Add Spanish locale (Merge 1a482cf)\n\nDocumentation:\n~~~~~~~~~~~~~~\n\n- a bit of polishing (Merge 4c88ea3)\n- removing confusing migrations paragraph (Merge 4c88ea3)\n\nContributors:\n~~~~~~~~~~~~~\n\n- KINOSHITA Shinji\n- Pavel Savchenko\n- Benny Daon\n- Mathieu Richardoz\n- Jos\u00e9 S\u00e1nchez Moreno\n\n\n1.0.6 - Bout Time\n-----------------\n\nThis release is long overdue, and includes some important fixes as well as general improvements to code and documentation.\n\nBug Fixes\n~~~~~~~~~\n\n- fixing TypeError: can only concatenate tuple (not \"list\") to tuple\n- ensure select2 is included last (Merge 9831ba5)\n- add script to load jQuery globally\n- remove invalid template variables\n- fix input focusing error in chrome\n- fix error when one missing range parameter caused error + test (Merge 365b646)\n\nFeatures\n~~~~~~~~\n\n- don't override original change_list_templates in AdminAdvancedFiltersMixin\n- make date range placeholder more pleasant (Merge 365b646)\n- add created_at field\n- Russian locale provided\n\nDocumentation\n~~~~~~~~~~~~~\n\n - make it clear easy-select2 is not required anymore (Merge 9831ba5)\n - Clarify how to import AdminAdvancedFiltersMixin in README\n\nTests\n~~~~~\n\n - add more fields/filter to test ModelAdmin\n\nContributors\n~~~~~~~~~~~~\n\n - Grigoriy Beziuk\n - \u041d\u0438\u043a\u0438\u0442\u0430 \u041a\u043e\u043d\u0438\u043d\n - Pavel Savchenko\n - Yuval Adam\n - Petr Dlouh\u00fd\n\n\n1.0.5 - Compatibility bump\n--------------------------\n\nBugs\n~~~~\n\n- updated AdvancedFilterQueryForm to include numeric comparison operators (Merge d3ee9f4)\n- Fixed a bug where editing an existing Advanced Filter defaulted all operators to 'Equals' (Merge d3ee9f4)\n- set AFQFormSet extra=0 instead of extra=1. I did this because having to check Delete is not clear to end users. (Merge d3ee9f4)\n- changed the Advanced Filter admin so you a User by default can only view/edit filters that they create (unless they are a superuser) (Merge d3ee9f4)\n- Fixed failing tests. Fixed bug where users weren't properly getting permissions to change or delete their filters (Merge d3ee9f4)\n- changed solution for extra form appearing on editing. Now initialize form checks for falsy value for extra rather than extra just being None (Merge d3ee9f4)\n- removed 'not instance from requirements for no extras (Merge d3ee9f4)\n- pep8 fix (Merge d3ee9f4)\n- Fixed labeling error with 'Greater Than or Equal To' (Merge d3ee9f4)\n- Changes URL declaration to avoid deprecated pattern\n- select2 only initializes if there are choices available. otherwise, the standard text input will be used (Merge 35d7063)\n- Revert \"select2 only initializes if there are choices available. otherwise, the standard text input will be used\" (Merge 35d7063)\n- updated query for choices for select2 field so that it will take only distinct choices. This allows max_choices to be the maximum unique choices. (Merge 35d7063)\n- Changes URL declaration to avoid deprecated pattern (Merge 35d7063)\n- refactored retrieval of choices so that the db is getting distinct values; added test (Merge 35d7063)\n- pep8 (Merge 35d7063)\n- Use order_by to avoid ambiguity\n- drop django-easy-select2 and include select2 directly\n\nTests\n~~~~~\n\n- test with both Python 3.5 and Django 1.10\n- removed print statement from test (Merge 35d7063)\n- fixed failing test to account for new distinct for max choices (Merge 35d7063)\n- added test to make sure all operators are properly restored from Queries (Merge d3ee9f4)\n\nContributors\n~~~~~~~~~~~~\n\n- Pavel Savchenko\n- PJ Passalacqua\n- Hermano Cabral\n\n\n1.0.4 - Unbreak Python 3\n------------------------\n\nThis release contains a fix to allow distribution installation on Python 3 which was broken since 1.0.2\n\n1.0.3 - The Package Fix\n-----------------------\n\nThis is a quick fix for packaging (setup.py) errors and documentation.\n\nBugs\n~~~~\n\n- add missing Django 1.7 migrations\n- README updated to mention ``manage.py migrate`` command\n- Use ReST for README and CHANGELOG: avoid conversion from markdown\n\n\n1.0.2 - A Better Future\n-----------------------\n\nThis release features better test coverage and support for Django 1.9.\n\nBugs\n~~~~\n\n- stretch formset table to the modal container width\n- toggle advanced ``vendor/jquery`` dir according to Django version\n- retain support older Django versions\n- clean up legacy tags in templates\n\nTests\n~~~~~\n\n- add admin views tests\n- add Django 1.9 to test matrix\n- other minor improvements\n\nDocs\n~~~~\n\n- Improve README with a newer screenshot and pretty tables for badges\n\nContributors:\n~~~~~~~~~~~~~\n\n- Pavel Savchenko\n- Leonardo J. Caballero G\n- Schuyler Duveen\n\n1.0.1 - A Public Release\n------------------------\n\nBugs\n~~~~\n\n- proper support for py26 and py3X and different Django releases\n- avoid querying all instances for choices\n- resolve settings inside view and refine error handling\n\nTests\n~~~~~\n\n- add doctests to the ``form_helpers``\n- add tests for ``forms``\n- add test case ``views.TestGetFieldChoicesView``\n- setup.py/travis: add ``test-reqs.txt`` as extras\\_require\n- refactor testing to use ``py.test`` and run ``tox`` from ``setup.py``\n- travis: use latest version of each Django release\n\nDocs:\n~~~~~\n\n- ``README``: explain what we test against\n\n1.0 - First contact\n-------------------\n\nMajor changes\n~~~~~~~~~~~~~\n\n- Add a new (required) field\n ```AdvancedFilter.model`` <https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/README.rst#model-correlation>`__\n- Add parsing query dict into initialized formsets (allows for `editing\n existing\n instance <https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/README.rst#editing-previously-created-advanced-filters>`__).\n- Add\n ```AdvancedFilterAdmin`` <#editing-previously-created-advanced-filters>`__\n for actually accessing and `editing existing ``AdvancedFilter``\n instances <https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/README.rst#editing-previously-created-advanced-filters>`__.\n- Use `Select2 <https://github.com/asyncee/django-easy-select2>`__ and\n an AJAX view to dynamically populate ```field``\n options <https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/README.rst#fields>`__.\n- Add proper support for nested serialization of queries.\n\nMinor changes\n~~~~~~~~~~~~~\n\n- Implement more ```operators`` <https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/README.rst#operators>`__ (``isnull``,\n ``istrue`` and ``isfalse``)\n- Allow `custom verbose naming of fields in\n advanced\\_filter\\_fields <https://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/README.rst#custom-naming-of-fields>`__\n- Add helper methods to the model to hide (and decouple) core\n serialization functionality from users.\n- Strip whitespace in field values validation\n- Setup and packaging (``setup.py``/``MANIFEST.in``)\n- Hide ``QSerializer`` calling logic in the model\n- Allow modifying ``advanced_filter_form`` property (defaults to\n ``AdvancedFilterForm``)\n- Correct documentation regarding position of mixin in subclass (issue\n #1)\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Django application for advanced admin filters",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/modlinltd/django-advanced-filters"
},
"split_keywords": [
"django-admin",
"admin",
"advanced",
"filters",
"custom",
"query"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b0e26b90404c40837ef4875ba1807745f1d93c6bf4107647d29732f1892fe746",
"md5": "2b5617a0be8dda001b4f521f9c8ed886",
"sha256": "60a4b224626e042a5ea657600efcdae8d214cf530fd2e6cc3e37d451d777f7a9"
},
"downloads": -1,
"filename": "django_advanced_filters-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2b5617a0be8dda001b4f521f9c8ed886",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 71002,
"upload_time": "2022-06-27T07:25:59",
"upload_time_iso_8601": "2022-06-27T07:25:59.470390Z",
"url": "https://files.pythonhosted.org/packages/b0/e2/6b90404c40837ef4875ba1807745f1d93c6bf4107647d29732f1892fe746/django_advanced_filters-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "eba547d761549782124270e97079c7920bec0ef6ae38e6ec47f612df3d87c7e8",
"md5": "4e7e3e108102a22124dd4213cb121fe3",
"sha256": "845c5e7121c9dd68ddcf850a2325e1b5f76f355c677215623bd8974a0359d783"
},
"downloads": -1,
"filename": "django-advanced-filters-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "4e7e3e108102a22124dd4213cb121fe3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 78685,
"upload_time": "2022-06-27T07:26:06",
"upload_time_iso_8601": "2022-06-27T07:26:06.125448Z",
"url": "https://files.pythonhosted.org/packages/eb/a5/47d761549782124270e97079c7920bec0ef6ae38e6ec47f612df3d87c7e8/django-advanced-filters-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-06-27 07:26:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "modlinltd",
"github_project": "django-advanced-filters",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "django-advanced-filters"
}
JSON
