Recipes¶

Single binding (Company ↔ Department)¶

from django.contrib import admin
from django.db.models import Q
from django_admin_reversefields.mixins import ReverseRelationAdminMixin, ReverseRelationConfig

def unbound_or_current(queryset, instance, request):
    if instance and instance.pk:
        return queryset.filter(Q(company__isnull=True) | Q(company=instance))
    return queryset.filter(company__isnull=True)

@admin.register(Company)
class CompanyAdmin(ReverseRelationAdminMixin, admin.ModelAdmin):
    reverse_relations = {
        "department_binding": ReverseRelationConfig(
            model=Department,
            fk_field="company",
            limit_choices_to=unbound_or_current,
            # Add bulk=True for better performance with large datasets
            # bulk=True,  # Uncomment if you don't need model signals
        )
    }
    fieldsets = (("Departments", {"fields": ("department_binding",)}),)

Note

Rendering Rules

If you declare fieldsets or fields, include the virtual name (e.g., "department_binding") so Django renders it.
If neither is declared, Django renders all form fields and the injected virtual fields appear automatically. The mixin appends the virtual names in get_fields and injects their form fields in get_form.
If you override get_fields without calling super(), or you return a custom fields list that omits the virtual names, the admin template will not render them (even though the form contains them).

Multiple binding (Company ↔ Projects)¶

from django.db.models import Q


def available_projects_queryset(queryset, instance, request):
    if instance and instance.pk:
        return queryset.filter(Q(company__isnull=True) | Q(company=instance))
    return queryset.filter(company__isnull=True)


@admin.register(Company)
class CompanyAdmin(ReverseRelationAdminMixin, admin.ModelAdmin):
    reverse_relations = {
        "assigned_projects": ReverseRelationConfig(
            model=Project,
            fk_field="company",
            multiple=True,
            ordering=("name",),
            limit_choices_to=available_projects_queryset,
            # Enable bulk operations for better performance with many projects
            # bulk=True,  # Uncomment if you don't need model signals
        )
    }
    fieldsets = (("Projects", {"fields": ("assigned_projects",)}),)
    # Rendering rules are the same as the single-binding recipe.
    # Ensure all updates occur as a single unit (default True)
    reverse_relations_atomic = True

Validation hooks (business rules)¶

Forbid unbinding unless a condition is met:

from django import forms

def forbid_unbind(instance, selection, request):
    if selection is None:
        raise forms.ValidationError("Cannot unbind department right now")

@admin.register(Company)
class CompanyAdmin(ReverseRelationAdminMixin, admin.ModelAdmin):
    reverse_relations = {
        "department_binding": ReverseRelationConfig(
            model=Department,
            fk_field="company",
            multiple=False,
            clean=forbid_unbind,
        )
    }

Permissions on reverse fields ¶

OneToOneField (Company ↔ CompanySettings)¶

def only_unbound_or_current(qs, instance, request):
    if instance and instance.pk:
        return qs.filter(Q(company__isnull=True) | Q(company=instance))
    return qs.filter(company__isnull=True)

@admin.register(Company)
class CompanyAdmin(ReverseRelationAdminMixin, admin.ModelAdmin):
    reverse_relations = {
        "settings_binding": ReverseRelationConfig(
            model=CompanySettings,
            fk_field="company",
            multiple=False,
            required=True,
            limit_choices_to=only_unbound_or_current,
        )
    }
    fieldsets = (("Settings", {"fields": ("settings_binding",)}),)

Request-aware validation hook (use request.user)¶

Sometimes validation must depend on the current user or other request context. The clean hook receives the request so you can implement user-specific rules.

from django import forms
from django.contrib import admin
from django_admin_reversefields.mixins import ReverseRelationAdminMixin, ReverseRelationConfig

def staff_only(instance, selection, request):
    if not getattr(request, "user", None) or not request.user.is_staff:
        raise forms.ValidationError("Not permitted")

@admin.register(Company)
class CompanyAdmin(ReverseRelationAdminMixin, admin.ModelAdmin):
    reverse_relations = {
        "department_binding": ReverseRelationConfig(
            model=Department,
            fk_field="company",
            multiple=False,
            required=False,
            clean=staff_only,  # gets (instance, selection, request)
        )
    }

If the user is not staff, the form will include a field error on department_binding with the message “Not permitted” and the update will be blocked.

Render-time policy (control visibility/editability before selection)¶

Enable reverse_render_uses_field_policy to let per-field or global policies decide whether a virtual field is visible or editable at render time. This is useful when you want to hide or disable a field based on request.user or other context before any selection exists.

from django.contrib import admin
from django_admin_reversefields.mixins import (
    ReverseRelationAdminMixin,
    ReverseRelationConfig,
)

# Hide binding from non-staff users at render time
def staff_only_policy(request, obj, config, selection):
    return getattr(request.user, "is_staff", False)

@admin.register(Company)
class CompanyAdmin(ReverseRelationAdminMixin, admin.ModelAdmin):
    reverse_permissions_enabled = True
    reverse_permission_mode = "hide"  # or "disable"
    reverse_render_uses_field_policy = True
    reverse_relations = {
        "department_binding": ReverseRelationConfig(
            model=Department,
            fk_field="company",
            multiple=False,
            permission=staff_only_policy,
        )
    }

With hide mode, a field is removed entirely for non-staff users. Switch to disable to keep it visible but read-only. Policies are evaluated with selection=None during render.

Bulk operations for performance optimization ¶

When managing large numbers of reverse relationships, enable bulk mode to use Django’s .update() method instead of individual model saves. This provides significant performance improvements but bypasses model signals.

from django.contrib import admin
from django.db.models import Q
from django_admin_reversefields.mixins import ReverseRelationAdminMixin, ReverseRelationConfig

def available_departments_queryset(queryset, instance, request):
    if instance and instance.pk:
        return queryset.filter(Q(company__isnull=True) | Q(company=instance))
    return queryset.filter(company__isnull=True)

@admin.register(Company)
class CompanyAdmin(ReverseRelationAdminMixin, admin.ModelAdmin):
    reverse_relations = {
        # Single-select with bulk operations
        "primary_department": ReverseRelationConfig(
            model=Department,
            fk_field="company",
            bulk=True,  # Use bulk operations for performance
            limit_choices_to=available_departments_queryset,
        ),
        # Multi-select with bulk operations - ideal for large datasets
        "all_projects": ReverseRelationConfig(
            model=Project,
            fk_field="company",
            multiple=True,
            bulk=True,  # Bulk operations for multiple selections
            ordering=("name",),
            limit_choices_to=available_departments_queryset,
        ),
        # Mixed configuration - some bulk, some individual
        "critical_departments": ReverseRelationConfig(
            model=Department,
            fk_field="company",
            multiple=True,
            bulk=False,  # Keep individual saves for signal processing
            ordering=("name",),
        )
    }
    fieldsets = (
        ("Department Assignments", {"fields": ("primary_department", "all_projects")}),
        ("Critical Departments", {"fields": ("critical_departments",)}),
    )

Note

Performance Guidelines

Use bulk mode when: Managing hundreds/thousands of objects, performance is critical, no signal dependencies
Avoid bulk mode when: Models rely on pre_save/post_save signals, need granular error handling
Mixed approach: Use bulk for high-volume fields, individual saves for signal-dependent fields

Warning

Signal Bypass Warning: Bulk operations use .update() which bypasses:

pre_save and post_save signals
Model save() method overrides
Custom validation in save() methods
Audit logging that depends on save signals

Only enable bulk mode when these features aren’t required for your reverse relationship model.