# django-dynamic-raw-id
A Django admin raw_id_fields widget replacement that handles display of an object's
string value on change and can be overridden via a template.
See this example:
<img src="https://d.pr/i/1kv7d.png" style="max-height: 500px;" alt="Screenshot of Django Admin"/>
## Compatibility Matrix:
| Py/Dj | 3.8 | 3.9 | 3.10 | 3.11 | 3.12 |
|-----------|-----|-----|------|------|------|
| 3.2 (LTS) | ✓ | ✓ | ✓ | ✓ | ✓ |
| 4.0 | ✓ | ✓ | ✓ | ✓ | ✓ |
| 4.1 | ✓ | ✓ | ✓ | ✓ | ✓ |
| 4.2 (LTS) | ✓ | ✓ | ✓ | ✓ | ✓ |
| 5.0 | — | — | ✓ | ✓ | ✓ |
## Rationale
By default, Django’s admin loads all possible related instances into a select-box
interface (`<select>`) for fields that are ForeignKey. This can result in long load
times and unresponsive admin pages for models with thousands of instances, or with
multiple ForeinKeys.
The normal fix is to use Django's [ModelAdmin.raw_id_fields](https://docs.djangoproject.com/en/4.0/ref/contrib/admin/#django.contrib.admin.ModelAdmin.raw_id_fields),
but by default it *only* shows the raw id of the related model instance, which is
somewhat unhelpful.
This package improves the user experience by providing the string representation or
other customized text for the related instance, linked to that instance's admin
change form, in addition to the raw id itself.
## Installation
Install the package with `pip``:
```bash
$ pip install django-dynamic-raw-id
```
Put `dynamic_raw_id` to your list of `INSTALLED_APPS`:
```python
INSTALLED_APPS = (
# ... other apps
'dynamic_raw_id',
)
```
And add the `urlpattern`. Make sure its listed *before* the generic `admin.site.urls`
urlpattern include:
```python
urlpatterns = [
# ...
path('admin/dynamic_raw_id/', include('dynamic_raw_id.urls')),
path("admin/", admin.site.urls),
]
```
`dynamic_raw_id` comes with some static files so don't forget to run
`manage.py collectstatic`.
## Usage
To start using django-dynamic-raw-id in your application all you need to do is
implement `DynamicRawIDMixin` in your `ModelAdmin` class and add the desired
fields to a list of `dynamic_raw_id_fields``:
```python
from dynamic_raw_id.admin import DynamicRawIDMixin
class UserProfileAdmin(DynamicRawIDMixin, admin.ModelAdmin):
dynamic_raw_id_fields = ('user',)
```
You can use dynamic_raw_id widgets in a Admin filter as well:
```python
from dynamic_raw_id.admin import DynamicRawIDMixin
from dynamic_raw_id.filters import DynamicRawIDFilter
class UserProfileAdmin(DynamicRawIDMixin, admin.ModelAdmin):
list_filter = (
('dynamic_raw_id_fk', DynamicRawIDFilter),
)
```
### Customizing the value of the dynamic widget
The coolest feature of django-dynamic-raw-id is the ability to customize the output
of the value displayed alongside the `DynamicRawIDWidget`. There is a basic
implementation if all you want is your object's `__unicode__` value. To change
the value displayed all you need to do is implement the correct template.
django-dynamic-raw-id looks for this template
structure `dynamic_raw_id/<app>/<model>.html``
and `dynamic_raw_id/<app>/multi_<model>.html` (for multi-value lookups).
For instance, if I have a blog post with a `User` dynamic_raw_id field that I want
display as `Firstname Lastname``, I would create the template
``dynamic_raw_id/auth/user.html` with:
```html
<span>{{ object.0.first_name }} {{ object.0.last_name }}</span>
```
A custom admin URL prefix
=========================
If you have your admin *and* the dynamic_raw_id scripts located on a different
prefix than `/admin/dynamic_raw_id/` you need adjust the `DYNAMIC_RAW_ID_MOUNT_URL``
JS variable.
Example:
```python
# In case the app is setup at /foobar/dynamic_raw_id/
path('foobar/dynamic_raw_id/', include('dynamic_raw_id.urls')),
```
```html
<script>window.DYNAMIC_RAW_ID_MOUNT_URL = "{% url "
admin:index
" %}";</script>
```
An ideal place is the admin `base_site.html` template. Full example:
```html
{% extends "admin/base.html" %}
{% block title %}{{ title }} | {{ site_title|default:_('Django site admin') }}{% endblock %}
{% block extrahead %}
{{ block.super }}
<script>
window.DYNAMIC_RAW_ID_MOUNT_URL = "{% url "
admin:index
" %}";
</script>
{% endblock %}
{% block branding %}
<h1 id="site-name"><a href="{% url 'admin:index' %}">{{ site_header|default:_('Django
administration') }}</a></h1>
{% endblock %}
{% block nav-global %}{% endblock %}
```
Testing and Local Development
=============================
The testsuite uses Selenium to do frontend tests, we require Firefox and
[geckodriver](https://github.com/mozilla/geckodriver) to be installed. You can
install geckodriver on OS X with Homebrew:
```bash
$ brew install geckodriver
```
Run the testsuite in your local environment using:
```bash
# If you don't have Poetry yet, install it globally.
$ pip install poetry
# Install Dependencies once and run pytest
$ poetry install
$ poetry run pytest
```
Or use tox to test against various Django and Python versions:
```bash
# If you don't have Tox yet, install it globally.
$ pip install tox
# Run tox against multiple Python versions.
$ tox
```
You can open a Poetry shell to invoke the test suite or other 'manage.py' commands
by calling the `django-admin` tool with the test app settings.
This also allows you to run the internal testing app in a testserver, to preview a
sample of what django-dynamic-raw-id is doing:
```shell
$ poetry shell
$ django-admin migrate
$ django-admin createsuperuser
$ django-admin runserver
```
# Changelog
## v4.0 (2024-04-21)
- Django 4.2 compatibility and tests.
- Django 5.0 compatibility and tests.
- Requires Python 3.8 or up.
- Switch package management to Poetry.
## v3.0 (2022-03-20)
- Django 4.0 compatibility and tests.
- Requires Django 3.2 or up.
- Requires Python 3.7 or up.
- *Note:* You may now need to change the order and put the dynamic-raw-id
include before the generic admin include. See Readme for details.
## v2.8 (2020-12-02)
- Django 3.1 compatibility and tests.
## v2.7 (2020-05-02)
- Django 3.0 compatibility and tests.
## v2.6 (2019-06-21)
- BACKWARDS INCOMPATIBLE: Dropped support for Django <1.11.
- BACKWARDS INCOMPATIBLE: Dropped support for Python 3.4.
- Django 2.2 compatibility and tests.
- General code cleanup.
- Pipenv support for local development.
- Some visual fixes around icons and alignment.
## v2.5 (2018-12-09)
- Django 2.1 compatibility and tests.
## v2.4 (2018-04-09)
- Fixes missing icons in Admin views.
- Fixes missing JS handling when using a custom /admin/ url.
## v2.3 (2018-01-18)
- BACKWARDS INCOMPATIBLE: Renamed the project to `django-dynamic-raw-id`.
to reflect what it's actually doing.
- Fixed glass lookup icon in Django 1.10 and below.
- Specific ordering of media asset loading.
## v1.2 (2018-01-17)
- Multiple fixes and enhancements.
- Full Selenium based testsuite.
- Django 2.0 and Python 3 compatibility.
- pipenv support.
Raw data
{
"_id": null,
"home_page": "https://github.com/lincolnloop/django-dynamic-raw-id",
"name": "django-dynamic-raw-id",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "django, widget, field, admin, raw-id, foreignkey",
"author": "Martin Mahner",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/1d/a2/ce1823a9b10e9d588e0094380b63fd534a3c7aa411142043bac96d9aa625/django_dynamic_raw_id-4.0.tar.gz",
"platform": null,
"description": "\n\n\n# django-dynamic-raw-id\n\nA Django admin raw_id_fields widget replacement that handles display of an object's\nstring value on change and can be overridden via a template.\n\nSee this example:\n\n<img src=\"https://d.pr/i/1kv7d.png\" style=\"max-height: 500px;\" alt=\"Screenshot of Django Admin\"/>\n\n## Compatibility Matrix:\n\n| Py/Dj | 3.8 | 3.9 | 3.10 | 3.11 | 3.12 |\n|-----------|-----|-----|------|------|------|\n| 3.2 (LTS) | \u2713 | \u2713 | \u2713 | \u2713 | \u2713 |\n| 4.0 | \u2713 | \u2713 | \u2713 | \u2713 | \u2713 |\n| 4.1 | \u2713 | \u2713 | \u2713 | \u2713 | \u2713 |\n| 4.2 (LTS) | \u2713 | \u2713 | \u2713 | \u2713 | \u2713 |\n| 5.0 | \u2014 | \u2014 | \u2713 | \u2713 | \u2713 |\n\n## Rationale\n\nBy default, Django\u2019s admin loads all possible related instances into a select-box\ninterface (`<select>`) for fields that are ForeignKey. This can result in long load\ntimes and unresponsive admin pages for models with thousands of instances, or with\nmultiple ForeinKeys.\n\nThe normal fix is to use Django's [ModelAdmin.raw_id_fields](https://docs.djangoproject.com/en/4.0/ref/contrib/admin/#django.contrib.admin.ModelAdmin.raw_id_fields),\nbut by default it *only* shows the raw id of the related model instance, which is\nsomewhat unhelpful.\n\nThis package improves the user experience by providing the string representation or\nother customized text for the related instance, linked to that instance's admin\nchange form, in addition to the raw id itself.\n\n## Installation\n\nInstall the package with `pip``:\n\n```bash\n$ pip install django-dynamic-raw-id\n```\n\nPut `dynamic_raw_id` to your list of `INSTALLED_APPS`:\n\n```python\nINSTALLED_APPS = (\n # ... other apps\n 'dynamic_raw_id',\n)\n```\n\nAnd add the `urlpattern`. Make sure its listed *before* the generic `admin.site.urls`\nurlpattern include:\n\n```python\nurlpatterns = [\n # ...\n path('admin/dynamic_raw_id/', include('dynamic_raw_id.urls')),\n path(\"admin/\", admin.site.urls),\n]\n```\n\n`dynamic_raw_id` comes with some static files so don't forget to run\n`manage.py collectstatic`.\n\n## Usage\n\nTo start using django-dynamic-raw-id in your application all you need to do is\nimplement `DynamicRawIDMixin` in your `ModelAdmin` class and add the desired\nfields to a list of `dynamic_raw_id_fields``:\n\n```python\nfrom dynamic_raw_id.admin import DynamicRawIDMixin\n\nclass UserProfileAdmin(DynamicRawIDMixin, admin.ModelAdmin):\n dynamic_raw_id_fields = ('user',)\n```\n\nYou can use dynamic_raw_id widgets in a Admin filter as well:\n\n```python\nfrom dynamic_raw_id.admin import DynamicRawIDMixin\nfrom dynamic_raw_id.filters import DynamicRawIDFilter\n\n\nclass UserProfileAdmin(DynamicRawIDMixin, admin.ModelAdmin):\n list_filter = (\n ('dynamic_raw_id_fk', DynamicRawIDFilter),\n )\n```\n\n### Customizing the value of the dynamic widget\n\nThe coolest feature of django-dynamic-raw-id is the ability to customize the output\nof the value displayed alongside the `DynamicRawIDWidget`. There is a basic\nimplementation if all you want is your object's `__unicode__` value. To change\nthe value displayed all you need to do is implement the correct template.\n\ndjango-dynamic-raw-id looks for this template\nstructure `dynamic_raw_id/<app>/<model>.html``\nand `dynamic_raw_id/<app>/multi_<model>.html` (for multi-value lookups).\n\nFor instance, if I have a blog post with a `User` dynamic_raw_id field that I want\ndisplay as `Firstname Lastname``, I would create the template\n``dynamic_raw_id/auth/user.html` with:\n\n```html\n<span>{{ object.0.first_name }} {{ object.0.last_name }}</span>\n```\n\nA custom admin URL prefix\n=========================\n\nIf you have your admin *and* the dynamic_raw_id scripts located on a different\nprefix than `/admin/dynamic_raw_id/` you need adjust the `DYNAMIC_RAW_ID_MOUNT_URL``\nJS variable.\n\nExample:\n\n```python\n # In case the app is setup at /foobar/dynamic_raw_id/\npath('foobar/dynamic_raw_id/', include('dynamic_raw_id.urls')),\n```\n\n```html\n\n<script>window.DYNAMIC_RAW_ID_MOUNT_URL = \"{% url \"\nadmin:index\n\" %}\";</script>\n```\n\nAn ideal place is the admin `base_site.html` template. Full example:\n\n```html\n{% extends \"admin/base.html\" %}\n\n{% block title %}{{ title }} | {{ site_title|default:_('Django site admin') }}{% endblock %}\n\n{% block extrahead %}\n{{ block.super }}\n<script>\n window.DYNAMIC_RAW_ID_MOUNT_URL = \"{% url \"\n admin:index\n \" %}\";\n</script>\n{% endblock %}\n\n{% block branding %}\n<h1 id=\"site-name\"><a href=\"{% url 'admin:index' %}\">{{ site_header|default:_('Django\n administration') }}</a></h1>\n{% endblock %}\n\n{% block nav-global %}{% endblock %}\n```\n\nTesting and Local Development\n=============================\n\nThe testsuite uses Selenium to do frontend tests, we require Firefox and\n[geckodriver](https://github.com/mozilla/geckodriver) to be installed. You can\ninstall geckodriver on OS X with Homebrew:\n\n```bash\n$ brew install geckodriver\n```\n\nRun the testsuite in your local environment using:\n\n```bash\n# If you don't have Poetry yet, install it globally.\n$ pip install poetry\n\n# Install Dependencies once and run pytest\n$ poetry install\n$ poetry run pytest\n```\n\nOr use tox to test against various Django and Python versions:\n\n```bash\n# If you don't have Tox yet, install it globally.\n$ pip install tox\n\n# Run tox against multiple Python versions.\n$ tox\n```\n\nYou can open a Poetry shell to invoke the test suite or other 'manage.py' commands\nby calling the `django-admin` tool with the test app settings.\n\nThis also allows you to run the internal testing app in a testserver, to preview a\nsample of what django-dynamic-raw-id is doing:\n\n```shell\n$ poetry shell\n\n$ django-admin migrate\n$ django-admin createsuperuser\n$ django-admin runserver\n```\n\n# Changelog\n\n## v4.0 (2024-04-21)\n\n- Django 4.2 compatibility and tests.\n- Django 5.0 compatibility and tests.\n- Requires Python 3.8 or up.\n- Switch package management to Poetry.\n\n## v3.0 (2022-03-20)\n\n- Django 4.0 compatibility and tests.\n- Requires Django 3.2 or up.\n- Requires Python 3.7 or up.\n- *Note:* You may now need to change the order and put the dynamic-raw-id\n include before the generic admin include. See Readme for details.\n\n## v2.8 (2020-12-02)\n\n- Django 3.1 compatibility and tests.\n\n## v2.7 (2020-05-02)\n\n- Django 3.0 compatibility and tests.\n\n## v2.6 (2019-06-21)\n\n- BACKWARDS INCOMPATIBLE: Dropped support for Django <1.11.\n- BACKWARDS INCOMPATIBLE: Dropped support for Python 3.4.\n- Django 2.2 compatibility and tests.\n- General code cleanup.\n- Pipenv support for local development.\n- Some visual fixes around icons and alignment.\n\n## v2.5 (2018-12-09)\n\n- Django 2.1 compatibility and tests.\n\n## v2.4 (2018-04-09)\n\n- Fixes missing icons in Admin views.\n- Fixes missing JS handling when using a custom /admin/ url.\n\n## v2.3 (2018-01-18)\n\n- BACKWARDS INCOMPATIBLE: Renamed the project to `django-dynamic-raw-id`.\n to reflect what it's actually doing.\n- Fixed glass lookup icon in Django 1.10 and below.\n- Specific ordering of media asset loading.\n\n## v1.2 (2018-01-17)\n\n- Multiple fixes and enhancements.\n- Full Selenium based testsuite.\n- Django 2.0 and Python 3 compatibility.\n- pipenv support.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "raw_id_fields widget replacement that handles display of an object's string value on change.",
"version": "4.0",
"project_urls": {
"Bugtracker": "https://github.com/lincolnloop/django-dynamic-raw-id/issues",
"Homepage": "https://github.com/lincolnloop/django-dynamic-raw-id",
"Source": "https://github.com/lincolnloop/django-dynamic-raw-id"
},
"split_keywords": [
"django",
" widget",
" field",
" admin",
" raw-id",
" foreignkey"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1d366a780094765f1dc092d7b8fd9bc2c80560c7de8cf25253f34a936b626b84",
"md5": "a660f0397c5e7bbca31e55e9603a4f62",
"sha256": "fec374bebe3ab5835895994b29295f738a29da6da4353de37cbb7aabc013d4d4"
},
"downloads": -1,
"filename": "django_dynamic_raw_id-4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a660f0397c5e7bbca31e55e9603a4f62",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 20910,
"upload_time": "2024-04-21T14:56:17",
"upload_time_iso_8601": "2024-04-21T14:56:17.069209Z",
"url": "https://files.pythonhosted.org/packages/1d/36/6a780094765f1dc092d7b8fd9bc2c80560c7de8cf25253f34a936b626b84/django_dynamic_raw_id-4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1da2ce1823a9b10e9d588e0094380b63fd534a3c7aa411142043bac96d9aa625",
"md5": "61e2d70eff6adc77c356eb2ba598a9e7",
"sha256": "0618230d82a7a9480714808dfd74e8e508bac5894cabffafe294b32681805d4d"
},
"downloads": -1,
"filename": "django_dynamic_raw_id-4.0.tar.gz",
"has_sig": false,
"md5_digest": "61e2d70eff6adc77c356eb2ba598a9e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 18785,
"upload_time": "2024-04-21T14:56:18",
"upload_time_iso_8601": "2024-04-21T14:56:18.505645Z",
"url": "https://files.pythonhosted.org/packages/1d/a2/ce1823a9b10e9d588e0094380b63fd534a3c7aa411142043bac96d9aa625/django_dynamic_raw_id-4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-21 14:56:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lincolnloop",
"github_project": "django-dynamic-raw-id",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-dynamic-raw-id"
}
JSON
