{"id":13468685,"url":"https://github.com/modlinltd/django-advanced-filters","last_synced_at":"2025-03-26T05:31:15.410Z","repository":{"id":11729708,"uuid":"14253654","full_name":"modlinltd/django-advanced-filters","owner":"modlinltd","description":"Add advanced filtering abilities to Django admin","archived":false,"fork":false,"pushed_at":"2024-07-30T05:57:59.000Z","size":651,"stargazers_count":790,"open_issues_count":54,"forks_count":176,"subscribers_count":19,"default_branch":"develop","last_synced_at":"2025-03-04T07:05:59.495Z","etag":null,"topics":["admin","django","filter","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/django-advanced-filters/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/modlinltd.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-11-09T07:54:45.000Z","updated_at":"2025-02-27T15:10:15.000Z","dependencies_parsed_at":"2024-03-25T14:54:18.545Z","dependency_job_id":"0ddbe486-e6b9-40c5-a097-d2051c3b16a5","html_url":"https://github.com/modlinltd/django-advanced-filters","commit_stats":{"total_commits":208,"total_committers":36,"mean_commits":5.777777777777778,"dds":"0.47115384615384615","last_synced_commit":"405670f910bbcb2e274736aca8a79bdbe1b283cc"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modlinltd%2Fdjango-advanced-filters","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modlinltd%2Fdjango-advanced-filters/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modlinltd%2Fdjango-advanced-filters/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modlinltd%2Fdjango-advanced-filters/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/modlinltd","download_url":"https://codeload.github.com/modlinltd/django-advanced-filters/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245597270,"owners_count":20641863,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["admin","django","filter","python"],"created_at":"2024-07-31T15:01:16.695Z","updated_at":"2025-03-26T05:31:13.673Z","avatar_url":"https://github.com/modlinltd.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"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 \u003chttps://www.vtiger.com/\u003e`__, `see here for more\ninfo \u003chttps://www.vtiger.com/docs/creating-custom-filters\u003e`__\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 \u003chttps://raw.githubusercontent.com/modlinltd/django-advanced-filters/develop/CHANGELOG.rst\u003e`__\n\nRequirements\n============\n\n-  Django 2.2, \u003e= 3.2 on Python 3.7+/PyPy3\n-  simplejson \u003e= 3.6.5, \u003c 4\n\n\nInstallation \u0026 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 \u003e= 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 \u003cdimsemenov/Magnific-Popup\u003e`__ 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. \u003c#integration-example\u003e`__\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 \u003chttps://docs.djangoproject.com/en/dev/topics/db/queries/#complex-lookups-with-q-objects\u003e`__.\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 \u003chttps://docs.djangoproject.com/en/dev/ref/models/querysets/#field-lookups\u003e`__.\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 \u003chttps://docs.djangoproject.com/en/dev/topics/forms/formsets/\u003e`__,\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`` \u003c#editing-previously-created-advanced-filters\u003e`__.\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\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodlinltd%2Fdjango-advanced-filters","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmodlinltd%2Fdjango-advanced-filters","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodlinltd%2Fdjango-advanced-filters/lists"}