# Django Query Builder Widget
A Django admin widget that integrates jQuery QueryBuilder for building complex database queries through an intuitive visual interface.
## Preview
<img width="1224" height="542" alt="image" src="https://github.com/user-attachments/assets/e14befe9-fd88-4a05-a0ea-a440c3c72469" />
## Features
- Visual query building interface in Django admin
- Automatic field detection from Django models
- Support for all major Django field types
- Customizable operators per field type
- Support for custom fields and operators
- JSON-based query storage
- Works seamlessly with Django admin
## Installation
Install via pip:
```bash
pip install django-query-builder-widget
```
## Quick Start
### 1. Add to your Django project
Add the app to your `INSTALLED_APPS` in `settings.py`:
```python
INSTALLED_APPS = [
# ...
'django_query_builder_widget',
# ...
]
```
### 2. Collect static files
```bash
python manage.py collectstatic
```
### 3. Use in your admin
```python
from django.contrib import admin
from django_query_builder_widget import QueryBuilderWidget
from .models import YourModel
class YourModelAdmin(admin.ModelAdmin):
formfield_overrides = {
models.JSONField: {'widget': QueryBuilderWidget(model=YourModel)},
}
admin.site.register(YourModel, YourModelAdmin)
```
## Usage Examples
### Basic Usage with Model
```python
from django_query_builder_widget import QueryBuilderWidget
# Auto-generate filters from model fields
widget = QueryBuilderWidget(model=MyModel)
```
### Specify Specific Fields
```python
# Only include specific fields
widget = QueryBuilderWidget(
model=MyModel,
fields=['name', 'email', 'age', 'created_at']
)
```
### Custom Field Configuration
```python
widget = QueryBuilderWidget(
model=MyModel,
field_config={
'status': {
'widget': 'select',
'choices': [
('active', 'Active'),
('inactive', 'Inactive'),
('pending', 'Pending')
]
},
'priority': {
'operators': ['equal', 'not_equal', 'greater', 'less']
}
}
)
```
### Add Custom Filters
```python
widget = QueryBuilderWidget(
model=MyModel,
extra_filters=[
{
'id': 'custom_field',
'label': 'Custom Field',
'type': 'string',
'operators': ['equal', 'contains'],
'input': 'text'
}
]
)
```
## Field Type Mapping
The widget automatically maps Django field types to QueryBuilder types:
| Django Field | QueryBuilder Type | Default Operators |
|--------------|-------------------|-------------------|
| CharField, TextField, EmailField, URLField | string | equal, not_equal, contains, not_contains, begins_with, ends_with, is_null, is_not_null |
| IntegerField, BigIntegerField, PositiveIntegerField | integer | equal, not_equal, less, less_or_equal, greater, greater_or_equal, between, is_null, is_not_null |
| FloatField, DecimalField | double | equal, not_equal, less, less_or_equal, greater, greater_or_equal, between, is_null, is_not_null |
| BooleanField | boolean | equal |
| DateField | date | equal, not_equal, less, less_or_equal, greater, greater_or_equal, between, is_null, is_not_null |
| DateTimeField | datetime | equal, not_equal, less, less_or_equal, greater, greater_or_equal, between, is_null, is_not_null |
| TimeField | time | equal, not_equal, less, less_or_equal, greater, greater_or_equal, between |
| ForeignKey, OneToOneField | integer | equal, not_equal, less, less_or_equal, greater, greater_or_equal, between, is_null, is_not_null |
## Configuration Options
### Widget Parameters
- `model`: Django model class to generate filters from
- `fields`: List of field names to include (default: all fields)
- `field_config`: Dictionary of custom configurations per field
- `extra_filters`: List of additional custom filters
- `attrs`: Standard Django widget attributes
### Field Configuration Options
Each field can be customized with:
- `widget`: Input type ('text', 'textarea', 'select', 'radio', 'checkbox', 'number')
- `choices` or `values`: List of tuples or dictionary for select options
- `operators`: List of allowed operators for the field
## Output Format
The widget stores queries as JSON in the following format:
```json
{
"condition": "AND",
"rules": [
{
"id": "name",
"field": "name",
"type": "string",
"input": "text",
"operator": "contains",
"value": "John"
},
{
"condition": "OR",
"rules": [
{
"id": "age",
"field": "age",
"type": "integer",
"input": "number",
"operator": "greater",
"value": 25
}
]
}
]
}
```
## Requirements
- Python >= 3.8
- Django >= 3.2
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Credits
This widget integrates [jQuery QueryBuilder](https://querybuilder.js.org/) by Damien Sorel.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Support
If you encounter any issues or have questions, please file an issue on the GitHub repository.
Raw data
{
"_id": null,
"home_page": "https://github.com/Matheus-BM/django-query-builder-widget",
"name": "django-query-builder-widget",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "django, widget, query-builder, admin, filter",
"author": "MatheusBM",
"author_email": "MatheusBM <contato@matheusbm.com>",
"download_url": "https://files.pythonhosted.org/packages/73/6d/d4e286f372ffb4857437d7714c9d5e31370b6f86a6f1df051037dc1ac798/django_query_builder_widget-0.0.7.tar.gz",
"platform": null,
"description": "# Django Query Builder Widget\n\nA Django admin widget that integrates jQuery QueryBuilder for building complex database queries through an intuitive visual interface.\n\n## Preview\n<img width=\"1224\" height=\"542\" alt=\"image\" src=\"https://github.com/user-attachments/assets/e14befe9-fd88-4a05-a0ea-a440c3c72469\" />\n\n## Features\n\n- Visual query building interface in Django admin\n- Automatic field detection from Django models\n- Support for all major Django field types\n- Customizable operators per field type\n- Support for custom fields and operators\n- JSON-based query storage\n- Works seamlessly with Django admin\n\n## Installation\n\nInstall via pip:\n\n```bash\npip install django-query-builder-widget\n```\n\n## Quick Start\n\n### 1. Add to your Django project\n\nAdd the app to your `INSTALLED_APPS` in `settings.py`:\n\n```python\nINSTALLED_APPS = [\n # ...\n 'django_query_builder_widget',\n # ...\n]\n```\n\n### 2. Collect static files\n\n```bash\npython manage.py collectstatic\n```\n\n### 3. Use in your admin\n\n```python\nfrom django.contrib import admin\nfrom django_query_builder_widget import QueryBuilderWidget\nfrom .models import YourModel\n\nclass YourModelAdmin(admin.ModelAdmin):\n formfield_overrides = {\n models.JSONField: {'widget': QueryBuilderWidget(model=YourModel)},\n }\n\nadmin.site.register(YourModel, YourModelAdmin)\n```\n\n## Usage Examples\n\n### Basic Usage with Model\n\n```python\nfrom django_query_builder_widget import QueryBuilderWidget\n\n# Auto-generate filters from model fields\nwidget = QueryBuilderWidget(model=MyModel)\n```\n\n### Specify Specific Fields\n\n```python\n# Only include specific fields\nwidget = QueryBuilderWidget(\n model=MyModel,\n fields=['name', 'email', 'age', 'created_at']\n)\n```\n\n### Custom Field Configuration\n\n```python\nwidget = QueryBuilderWidget(\n model=MyModel,\n field_config={\n 'status': {\n 'widget': 'select',\n 'choices': [\n ('active', 'Active'),\n ('inactive', 'Inactive'),\n ('pending', 'Pending')\n ]\n },\n 'priority': {\n 'operators': ['equal', 'not_equal', 'greater', 'less']\n }\n }\n)\n```\n\n### Add Custom Filters\n\n```python\nwidget = QueryBuilderWidget(\n model=MyModel,\n extra_filters=[\n {\n 'id': 'custom_field',\n 'label': 'Custom Field',\n 'type': 'string',\n 'operators': ['equal', 'contains'],\n 'input': 'text'\n }\n ]\n)\n```\n\n## Field Type Mapping\n\nThe widget automatically maps Django field types to QueryBuilder types:\n\n| Django Field | QueryBuilder Type | Default Operators |\n|--------------|-------------------|-------------------|\n| CharField, TextField, EmailField, URLField | string | equal, not_equal, contains, not_contains, begins_with, ends_with, is_null, is_not_null |\n| IntegerField, BigIntegerField, PositiveIntegerField | integer | equal, not_equal, less, less_or_equal, greater, greater_or_equal, between, is_null, is_not_null |\n| FloatField, DecimalField | double | equal, not_equal, less, less_or_equal, greater, greater_or_equal, between, is_null, is_not_null |\n| BooleanField | boolean | equal |\n| DateField | date | equal, not_equal, less, less_or_equal, greater, greater_or_equal, between, is_null, is_not_null |\n| DateTimeField | datetime | equal, not_equal, less, less_or_equal, greater, greater_or_equal, between, is_null, is_not_null |\n| TimeField | time | equal, not_equal, less, less_or_equal, greater, greater_or_equal, between |\n| ForeignKey, OneToOneField | integer | equal, not_equal, less, less_or_equal, greater, greater_or_equal, between, is_null, is_not_null |\n\n## Configuration Options\n\n### Widget Parameters\n\n- `model`: Django model class to generate filters from\n- `fields`: List of field names to include (default: all fields)\n- `field_config`: Dictionary of custom configurations per field\n- `extra_filters`: List of additional custom filters\n- `attrs`: Standard Django widget attributes\n\n### Field Configuration Options\n\nEach field can be customized with:\n\n- `widget`: Input type ('text', 'textarea', 'select', 'radio', 'checkbox', 'number')\n- `choices` or `values`: List of tuples or dictionary for select options\n- `operators`: List of allowed operators for the field\n\n## Output Format\n\nThe widget stores queries as JSON in the following format:\n\n```json\n{\n \"condition\": \"AND\",\n \"rules\": [\n {\n \"id\": \"name\",\n \"field\": \"name\",\n \"type\": \"string\",\n \"input\": \"text\",\n \"operator\": \"contains\",\n \"value\": \"John\"\n },\n {\n \"condition\": \"OR\",\n \"rules\": [\n {\n \"id\": \"age\",\n \"field\": \"age\",\n \"type\": \"integer\",\n \"input\": \"number\",\n \"operator\": \"greater\",\n \"value\": 25\n }\n ]\n }\n ]\n}\n```\n\n## Requirements\n\n- Python >= 3.8\n- Django >= 3.2\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Credits\n\nThis widget integrates [jQuery QueryBuilder](https://querybuilder.js.org/) by Damien Sorel.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Support\n\nIf you encounter any issues or have questions, please file an issue on the GitHub repository.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Django admin widget for building complex queries using jQuery QueryBuilder",
"version": "0.0.7",
"project_urls": {
"Homepage": "https://github.com/Matheus-BM/django-query-builder-widget",
"Issues": "https://github.com/Matheus-BM/django-query-builder-widget/issues",
"Repository": "https://github.com/Matheus-BM/django-query-builder-widget"
},
"split_keywords": [
"django",
" widget",
" query-builder",
" admin",
" filter"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "61943eb967dfb59938c54e98628189a99ae874ec907ec3fee21445dfb6b9100c",
"md5": "4281f38ab56286a76c82993accd5cb6d",
"sha256": "e95da95f743b58166c4770651f33c8efa46ac918ca285208de1270b758488c69"
},
"downloads": -1,
"filename": "django_query_builder_widget-0.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4281f38ab56286a76c82993accd5cb6d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 62677,
"upload_time": "2025-11-03T15:19:54",
"upload_time_iso_8601": "2025-11-03T15:19:54.878460Z",
"url": "https://files.pythonhosted.org/packages/61/94/3eb967dfb59938c54e98628189a99ae874ec907ec3fee21445dfb6b9100c/django_query_builder_widget-0.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "736dd4e286f372ffb4857437d7714c9d5e31370b6f86a6f1df051037dc1ac798",
"md5": "3cdc2efa5198cd4b8c376049d8c2ca68",
"sha256": "27a4a21973cd8019fa1e14bf4c20f927a971d891fc1c9d474a03cddf570e3433"
},
"downloads": -1,
"filename": "django_query_builder_widget-0.0.7.tar.gz",
"has_sig": false,
"md5_digest": "3cdc2efa5198cd4b8c376049d8c2ca68",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 63243,
"upload_time": "2025-11-03T15:19:56",
"upload_time_iso_8601": "2025-11-03T15:19:56.896107Z",
"url": "https://files.pythonhosted.org/packages/73/6d/d4e286f372ffb4857437d7714c9d5e31370b6f86a6f1df051037dc1ac798/django_query_builder_widget-0.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-03 15:19:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Matheus-BM",
"github_project": "django-query-builder-widget",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-query-builder-widget"
}
JSON
