Metadata-Version: 2.1
Name: django-dynamic-raw-id
Version: 3.0
Summary: raw_id_fields widget replacement that handles display of an object's string value on change.
Home-page: https://github.com/lincolnloop/django-dynamic-raw-id
Author: Martin Mahner, Seth Buntin, Yann Malet
Author-email: info@lincolnloop.com
License: MIT
Keywords: django,widget,field,admin,raw-id,foreignkey
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Framework :: Django
Requires-Python: >=3.7
Provides-Extra: tests
License-File: LICENSE

.. image:: https://img.shields.io/pypi/v/django-dynamic-raw-id.svg
    :target: https://pypi.org/project/django-dynamic-raw-id/

.. image:: https://github.com/lincolnloop/django-dynamic-raw-id/actions/workflows/test.yml/badge.svg
    :target: https://travis-ci.org/lincolnloop/django-dynamic-raw-id

----

=====================
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:

.. image:: http://d.pr/i/10GtM.png
    :target: http://d.pr/i/1kv7d.png

Compatibility Matrix:
=====================

========= === === === ====
Py/Dj     3.7 3.8 3.9 3.10
========= === === === ====
3.2         ✓   ✓   ✓   ✓
4.0         ✓   ✓   ✓   ✓
========= === === === ====

Installation
============


Install the package with ``pip``:

.. code-block:: bash

    $ pip install django-dynamic-raw-id

Put ``dynamic_raw_id`` to your list of ``INSTALLED_APPS``:

.. code-block:: python

    INSTALLED_APPS = (
        # ... other apps
        'dynamic_raw_id',
    )

And add the ``urlpattern``. Make sure its listed *before* the generic
``admin.site.urls`` urlpattern include:

.. code-block:: 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``:

.. code-block:: 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:

.. code-block:: 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:

.. code-block:: html+django

    <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:

.. code-block::

    # In case the app is setup at /foobar/dynamic_raw_id/
    url(r'^foobar/dynamic_raw_id/', include('dynamic_raw_id.urls')),

    # Provide a
    <script>
        window.DYNAMIC_RAW_ID_MOUNT_URL = "{% url "admin:index" %}";
    </script>

An ideal place is the admin ``base_site.html`` template. Full example:

.. code-block:: html+django

    {% 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_ to be installed. You can install geckodriver on OS X with
Homebrew:

.. code-block:: bash

    $ brew install geckodriver

Run the testsuite in your local environment using:

.. code-block:: bash

    $ cd django-dynamic-raw-id/
    $ pipenv install --dev
    $ pipenv run pytest

Or use tox to test against various Django and Python versions:

.. code-block:: bash

    $ tox -r

You can also invoke the test suite or other 'manage.py' commands by calling
the ``django-admin`` tool with the test app settings:

.. code-block:: bash

    $ cd django-dynamic-raw-id/
    $ pipenv install --dev
    $ pipenv run pytest

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:

.. code-block:: bash

    $ pipenv run django-admin migrate
    $ pipenv run django-admin createsuperuser
    $ pipenv run django-admin runserver

.. note:: The default settings file is set in the ``.env`` file which
   pipenv automatically exposes:

.. code-block:: bash

    DJANGO_SETTINGS_MODULE=dynamic_raw_id.tests.testapp.settings


.. _geckodriver: https://github.com/mozilla/geckodriver

=========
Changelog
=========

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.


