{"id":17543160,"url":"https://github.com/vb64/django.admin.filters","last_synced_at":"2025-04-13T06:37:05.304Z","repository":{"id":59065082,"uuid":"534677190","full_name":"vb64/django.admin.filters","owner":"vb64","description":"Embedded filters for Django Admin site","archived":false,"fork":false,"pushed_at":"2025-02-13T06:11:58.000Z","size":157,"stargazers_count":30,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-26T23:05:43.426Z","etag":null,"topics":["admin","calendar","checkbox","daterange","django","list-filter","multichoice","picker"],"latest_commit_sha":null,"homepage":"","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/vb64.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2022-09-09T14:30:02.000Z","updated_at":"2025-02-13T06:26:31.000Z","dependencies_parsed_at":"2023-10-04T13:18:24.446Z","dependency_job_id":"422b808b-b942-4b60-b3d3-1d530ed50771","html_url":"https://github.com/vb64/django.admin.filters","commit_stats":{"total_commits":33,"total_committers":1,"mean_commits":33.0,"dds":0.0,"last_synced_commit":"d171584c585aa191b79c1bc74a691e0739c4d3e3"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vb64%2Fdjango.admin.filters","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vb64%2Fdjango.admin.filters/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vb64%2Fdjango.admin.filters/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vb64%2Fdjango.admin.filters/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vb64","download_url":"https://codeload.github.com/vb64/django.admin.filters/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248675334,"owners_count":21143763,"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","calendar","checkbox","daterange","django","list-filter","multichoice","picker"],"created_at":"2024-10-21T00:23:05.145Z","updated_at":"2025-04-13T06:37:05.280Z","avatar_url":"https://github.com/vb64.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DjangoAdminFilters library\n\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/vb64/django.admin.filters/pep257.yml?label=Pep257\u0026style=plastic\u0026branch=main)](https://github.com/vb64/django.admin.filters/actions?query=workflow%3Apep257)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/vb64/django.admin.filters/django3.yml?label=Django%203.2.25\u0026style=plastic\u0026branch=main)](https://github.com/vb64/django.admin.filters/actions?query=workflow%3Adjango3)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/vb64/django.admin.filters/django4.yml?label=Django%204.2.19\u0026style=plastic\u0026branch=main)](https://github.com/vb64/django.admin.filters/actions?query=workflow%3Adjango4)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/vb64/django.admin.filters/django5.yml?label=Django%205.1.6\u0026style=plastic\u0026branch=main)](https://github.com/vb64/django.admin.filters/actions?query=workflow%3Adjango5)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/926ec3c1141f4230b4d0508497e5561f)](https://app.codacy.com/gh/vb64/django.admin.filters/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/926ec3c1141f4230b4d0508497e5561f)](https://app.codacy.com/gh/vb64/django.admin.filters/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_coverage)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/django-admin-list-filters?label=pypi%20installs)](https://pypistats.org/packages/django-admin-list-filters)\n\n[In Russian](READMEru.md)\n\nThe free, open-source DjangoAdminFilters library is designed to filter objects in the Django admin site.\nThe library provide few filters for this purpose.\n\n- `MultiChoice`: multi choice selection with checkboxes for CharField and IntegerField fields with 'choices' option\n- `MultiChoiceExt`: another version of previous filter, that allows filtering by custom defined properties\n- `DateRange`: set a custom date range using `input` fields\n- `DateRangePicker`: set a custom date range using javascript widget for select datetime from calendar\n\nMultiChoice and MultiChoiceExt | DateRange | DateRangePicker\n:------:|:-----:|:----:\n![MultiChoice filter](img/multi_choice_en.png) | ![DateRange with input field](img/daterange_en.png) | ![DateRange with js widget](img/picker_en.png)\n\nFor javascript widget for DateRangePicker was used code from [date-and-time-picker project](https://github.com/polozin/date-and-time-picker) with merged [pull request](https://github.com/polozin/date-and-time-picker/pull/4/files), that allow to select dates before current.\n\n## Installation\n\n```bash\npip install django-admin-list-filters\n```\n\nTo connect library to your project, add `django_admin_filters` to the `INSTALLED_APPS` list  in your `settings.py` file.\n\n```python\n\nINSTALLED_APPS = (\n\n...\n\n  'django_admin_filters',\n)\n```\n\nThen connect the static files of the library.\n\n```bash\nmanage.py collectstatic\n```\n\n## Initial data\n\nLet's say we have a table in the database. The records contain follows fields.\n\n```python\n# models.py\n\nfrom django.db import models\n\nSTATUS_CHOICES = (\n  ('P', 'Pending'),\n  ('A', 'Approved'),\n  ('R', 'Rejected'),\n)\n\nclass Log(models.Model):\n    text = models.CharField(max_length=100)\n\n    timestamp1 = models.DateTimeField(default=None, null=True)\n    timestamp2 = models.DateTimeField(default=None, null=True)\n\n    status = models.CharField(max_length=1, default='P', choices=STATUS_CHOICES)\n\n    is_online = models.BooleanField(default=False)\n    is_trouble1 = models.BooleanField(default=False)\n    is_trouble2 = models.BooleanField(default=False)\n```\n\n## Shared settings for all filters in the library\n\nYou can customize the appearance and behavior of filters to suit your needs by inheriting the filter classes from the library and overriding some of the attributes.\nAll library filters support the following attributes.\n\n```python\nfrom django_admin_filters import MultiChoice\n\nclass MyChoicesFilter(MultiChoice):\n    FILTER_LABEL = \"Select options\"\n    BUTTON_LABEL = \"Apply\"\n```\n\n- FILTER_LABEL: Filter title\n- BUTTON_LABEL: Title for filter apply button\n\n## MultiChoice filter\n\nFor model fields of type `CharField` or `IntegerField` defined using the `choices` parameter (for example, the 'status' field in the `Log` model), you can use the MultiChoice filter.\nValues  of the parameter `choices` will be displayed as checkboxes.\n\nTo use MultiChoice filter, you need to specify them in the `admin.py` file in the `list_filter` attribute of the corresponding class.\n\n```python\n# admin.py\n\nfrom django.contrib import admin\nfrom django_admin_filters import MultiChoice\nfrom .models import Log\n\nclass StatusFilter(MultiChoice):\n    FILTER_LABEL = \"By status\"\n\nclass Admin(admin.ModelAdmin):\n    list_display = ['text', 'status']\n    list_filter = [('status', StatusFilter)]\n\nadmin.site.register(Log, Admin)\n```\n\nIn the Django admin panel, check the required checkboxes in the filter and click the \"Apply\" button.\nIf all filter checkboxes are unchecked and the apply filter button is pressed, than the filter will not been aplied and all records will be displayed.\n\n## MultiChoiceExt filter\n\nSometimes you need to filter data by a custom defined property that does not match a single field in the model.\n\nFor example, in the `Log` model of the source data, there are three boolean fields.\n\n```python\n    is_online = models.BooleanField(default=False)\n    is_trouble1 = models.BooleanField(default=False)\n    is_trouble2 = models.BooleanField(default=False)\n```\n\nFor this model, we define the `color` property as follows.\n\n- The `color` property has the value 'red' if the field `is_online == False`.\n- If `is_online == True` and both `is_trouble1` and `is_trouble2` fields are False, then the value of the property is 'green'.\n- If `is_online == True` and at least one of the fields `is_trouble1` and `is_trouble2` is True, then the property has the value 'yellow'.\n\n```python\n# models.py\n\n    @property\n    def color(self):\n        status = 'red'\n        if self.is_online:\n            status = 'green'\n            if self.is_trouble1 or self.is_trouble2:\n                status = 'yellow'\n\n        return status\n```\n\nTo filter data by such a property in the Django admin panel, you can use the MultiChoiceExt filter.\nIn the `options` attribute, you need to specify a list of checkboxes that will be displayed when using the filter.\n\nEach element of the list consists of three values.\n\n- a unique string to be used in the GET request parameter\n- checkbox label\n- filtering expression applied to the DB model in the form of [Django Q-objects](https://docs.djangoproject.com/en/dev/topics/db/queries/#complex-lookups-with-q-objects)\n\nIn the `parameter_name` attribute, you need to specify the name of the GET request parameter for sending filter data.\n\nFor our example, the code will look like this.\n\n```python\n# admin.py\n\nfrom django.db.models import Q\nfrom django_admin_filters import MultiChoiceExt\n\nclass ColorFilter(MultiChoiceExt):\n    FILTER_LABEL = \"By color\"\n    parameter_name = \"color\"\n    options = [\n      ('red', 'Red', Q(is_online=False)),\n      ('yellow', 'Yellow', Q(is_online=True) \u0026 (Q(is_trouble1=True) | Q(is_trouble2=True))),\n      ('green', 'Green', Q(is_online=True) \u0026 Q(is_trouble1=False) \u0026 Q(is_trouble2=False)),\n    ]\n\nclass Admin(admin.ModelAdmin):\n    list_display = ['text', 'color']\n    list_filter = [ColorFilter]\n\nadmin.site.register(Log, Admin)\n```\n\nOtherwise, the behavior and settings of the `MultiChoiceExt` filter are similar to the `MultiChoice` filter described earlier.\n\n## DateRange and DateRangePicker filters\n\nTo use filters with a date interval, you need to specify them in the `admin.py` file in the `list_filter` attribute of the corresponding class.\n\n```python\n# admin.py\n\nfrom django.contrib import admin\nfrom django_admin_filters import DateRange, DateRangePicker\nfrom .models import Log\n\nclass Admin(admin.ModelAdmin):\n    list_display = ['text', 'timestamp1', 'timestamp2']\n    list_filter = (('timestamp1', DateRange), ('timestamp2', DateRangePicker))\n\nadmin.site.register(Log, Admin)\n```\n\n### Customization for DateRange filter\n\n```python\n# admin.py\n\nfrom django_admin_filters import DateRange\n\nclass MyDateRange(DateRange):\n    FILTER_LABEL = \"Data range\"\n    BUTTON_LABEL = \"Set range\"\n    FROM_LABEL = \"From\"\n    TO_LABEL = \"To\"\n    ALL_LABEL = 'All'\n    CUSTOM_LABEL = \"custom range\"\n    NULL_LABEL = \"no date\"\n    DATE_FORMAT = \"YYYY-MM-DD HH:mm\"\n\n    is_null_option = True\n\n    options = (\n      ('1da', \"24 hours ahead\", 60 * 60 * 24),\n      ('1dp', \"24 hours in the past\", 60 * 60 * -24),\n    )\n```\n\nYou can override the following attributes.\n\n- `FILTER_LABEL`: Title of the filter.\n- `BUTTON_LABEL`: Text on the apply filter button.\n- `FROM_LABEL`: The label of the start date field.\n- `TO_LABEL`: The label of the end date field.\n- `ALL_LABEL`: The label of the menu item for displaying all records.\n- `CUSTOM_LABEL`: The label of the menu item when date range is set.\n- `NULL_LABEL`: The label of the menu item for displaying records without date.\n- `is_null_option`: Set this attribute to `False` to remove the option to display record without date from the filter menu.\n- `parameter_start_mask`: Mask of the GET request parameter name for the start date of the date range.\n- `parameter_end_mask`: Mask of the GET request parameter name for the end date of the date range.\n- `DATE_FORMAT`: Hint about the format of the date and time fields.\n\nYou can change the date/time input format to your own.\nHowever, you may need to override the `to_dtime` method as well.\nThis method is used to convert a user-entered string into a `datetime` value.\nBy default, the method is defined as follows.\n\n```python\n@staticmethod\ndef to_dtime(text):\n    try:\n        return datetime.fromisoformat(text)\n    except ValueError:\n        return None\n```\n\nThe `options` attribute specifies filter menu items that allow you to select data from the current moment to an offset of a specified number of seconds in the past or future.\nEach element of the `options` list contains three values.\n\n- A unique string to use in the GET request parameters. Except for the strings 'custom' and 'empty' which are used by the filter.\n- The title of the item in the filter menu.\n- Offset in seconds relative to the current moment. A negative value specifies an offset to the past.\n\n### Customization for DateRangePicker filter\n\nThe `DateRangePicker` filter with a javascript calendar date/time picker widget is derived from the `DateRange` filter and allows you to override all the attributes described above.\nAlso, additional attributes can be overridden in `DateRangePicker`.\n\n```python\n# admin.py\n\nfrom django_admin_filters import DateRangePicker\n\nclass MyDateRangePicker(DateRangePicker):\n    WIDGET_LOCALE = 'en'\n    WIDGET_BUTTON_LABEL = \"Set\"\n    WIDGET_WITH_TIME = True\n\n    WIDGET_START_TITLE = 'Start date'\n    WIDGET_START_TOP = -350\n    WIDGET_START_LEFT = -400\n\n    WIDGET_END_TITLE = 'End date'\n    WIDGET_END_TOP = -350\n    WIDGET_END_LEFT = -400\n```\n\n- WIDGET_LOCALE: The language code for display the names of the months and days of the week. By default is the value of the `LANGUAGE_CODE` item in your project's `settings.py` file.\n- WIDGET_BUTTON_LABEL: The label of the select button.\n- WIDGET_WITH_TIME: Set this attribute to `False` if you only want to select a date without a time.\n- WIDGET_START_TITLE: The title of the widget when selecting the start date of the interval.\n- WIDGET_START_TOP: The vertical offset of the widget's calendar window when selecting the start date of the interval.\n- WIDGET_START_LEFT: The horizontal offset of the widget's calendar window when selecting the start date of the interval.\n- WIDGET_END_TITLE: The title of the widget when selecting the end date of the interval.\n- WIDGET_END_TOP: The vertical offset of the widget's calendar window when selecting the end date of the interval.\n- WIDGET_END_LEFT: The horizontal offset of the widget's calendar window when selecting the end date of the interval.\n\n## Usage example\n\nYou can run an example of using the library on your local host.\n\nOn the Windows platform, you must first install the following programs.\n\n- [Python3](https://www.python.org/downloads/release/python-3712/)\n- GNU [Unix Utils](http://unxutils.sourceforge.net/) for operations via makefile\n- [Git for Windows](https://git-scm.com/download/win) to access the source code repository.\n\nThen clone the repository and run the installation, specifying the path to Python 3.\n\n```bash\ngit clone git@github.com:vb64/django.admin.filters.git\ncd django.admin.filters\nmake setup PYTHON_BIN=/usr/bin/python3\n```\n\nCollect static files and create a database.\n\n```bash\nmake static\nmake db\n```\n\nCreate a database superuser by specifying a login and password for it.\n\n```bash\nmake superuser\n```\n\nRun example.\n\n```bash\nmake example\n```\n\nOpen `http://127.0.0.1:8000/admin/` in a browser to view the example site.\nTo enter the admin panel you need to use the login and password that were set when creating the superuser.\n\n## Related projects\n\n- [django-admin-list-filter-dropdown](https://github.com/mrts/django-admin-list-filter-dropdown) `DropdownFilter` class that renders as a drop-down in the filtering sidebar for Django admin list views.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvb64%2Fdjango.admin.filters","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvb64%2Fdjango.admin.filters","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvb64%2Fdjango.admin.filters/lists"}