Usage#
Installation#
Install from PyPI:
$ pip install django-relatives
Linking to foreign keys in change lists#
The easiest way to automatically to turn foreign key columns into hyperlinks in a Django admin change list is to inherit from RelativesAdmin
in your model admin.
Example#
from django.contrib import admin
from relatives import RelativesAdmin
from .models import Company, Employee
@admin.register(Company)
class CompanyAdmin(admin.ModelAdmin):
list_display = ["name"]
@admin.register(Employee)
class EmployeeAdmin(RelativesAdmin):
list_display = ["first_name", "last_name", "company"]
Screenshot#
When viewing the change list for the employee model, you’ll now see that the company column contents are all linked to the appropriate change form page for each company.
Linking to foreign keys in change forms#
The contents_or_fk_link
template filter can be used to link to foreign keys for readonly admin form fields.
Django Relatives also provides a replacement for the admin/includes/fieldset.html
template which can be used to automatically link to all readonly foreign key fields in change forms.
To use the custom fieldset template you must add relatives
to
INSTALLED_APPS
in your settings file:
INSTALLED_APPS = (
...
'relatives',
)
Next create a admin/includes/fieldset.html
template file:
{% extends "relatives/includes/fieldset.html" %}
Also make sure this template file is in a custom template directory or an app
listed before your admin app in INSTALLED_APPS
.
Example Screenshot#
Linking to reverse relations on change forms#
The related_objects
template tag makes it easy to link to change lists
filtered for reverse relations (objects that have a foreign key to a given
object).
Django Relatives also provides a custom change_form.html
template that may
be used to add a “Relations” sidebar to change forms. This sidebar provides
links to change list queries for all objects that contain a foreign key to the
current object.
To use the custom fieldset template you must add relatives
to
INSTALLED_APPS
in your settings file:
INSTALLED_APPS = (
...
'relatives',
)
Now you can customize the change form template for your desired models/apps.
The easiest way to link to reverse relations is to override the
change_form_template
in your ModelAdmin
subclass.
Example#
Code#
from django.contrib import admin
from .models import Company, Employee
admin.site.register(Employee)
@admin.register(Company, CompanyAdmin)
class CompanyAdmin(admin.ModelAdmin):
change_form_template = "relatives/change_form.html"
Screenshot#
Linking to reverse relations with custom template#
If you don’t have access to change the ModelAdmin
for your model or you are
already customizing your model’s admin change form, you will need to use a
custom admin template instead.
Create a admin/YOURAPP/YOURMODEL/change_form.html
template file that
extends from relatives/change_form.html
:
{% extends "relatives/change_form.html" %}
Also make sure this template file is in a custom template directory or an app
listed before your admin app in INSTALLED_APPS
.
Edit links in inlines#
To link to an inline object, include the object_link
utility function in your admin inline’s fields
list and readonly_fields
list.
Example#
Code#
from django.contrib import admin
from relatives.utils import object_link
from .models import Company, Employee
admin.site.register(Employee)
class EmployeeInline(admin.TabularInline):
model = Employee
fields = [object_link, "first_name", "last_name"]
readonly_fields = fields
extra = 0
max_num = 0
can_delete = False
@admin.register(Company)
class CompanyAdmin(admin.ModelAdmin):
inlines = [EmployeeInline]
Screenshot#
Customizing inline edit links#
To customize the link text for your inline links, use the object_edit_link
utility function instead, specifying the edit text and blank text (both are optional).
Example#
Code#
from django.contrib import admin
from relatives.utils import object_edit_link
from .models import Company, Employee
admin.site.register(Employee)
class EmployeeInline(admin.TabularInline):
model = Employee
edit_link = object_edit_link("Edit")
fields = [edit_link, "employee_id", "first_name", "last_name"]
readonly_fields = [edit_link]
@admin.register(Company)
class CompanyAdmin(admin.ModelAdmin):
inlines = [EmployeeInline]
Screenshot#
Customizing settings#
Since relatives uses cache, you can update the settings module to change the defaults if you’d like:
RELATIVES_CACHE_KEY = 'relatives_cache'
RELATIVES_CACHE_TIME = int(60*60*24)