Skip to content
An extension for Wagtail's ModelAdmin for a page explorer-like navigation of Django model relationships
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status Coverage Status

TreeModelAdmin illustration with the books and authors example below

Wagtail-TreeModelAdmin is an extension for Wagtail's ModelAdmin that allows for a page explorer-like navigation of Django model relationships within the Wagtail admin.


  • Python 2.7+, 3.6+
  • Django 1.11+, 2.0+
  • Wagtail 1.13+, 2.0+


  1. Install wagtail-treemodeladmin:
pip install wagtail-treemodeladmin
  1. Add treemodeladmin (and wagtail.contrib.modeladmin if it's not already) as an installed app in your Django


Wagtail-TreeModelAdmin allows for a Wagtail page explorer-like navigation of Django one-to-many relationships within the Wagtail admin. In doing this, it conceptualizes the Django ForeignKey relationship as one of parents-to-children. The parent is the destination to of the ForeignKey relationship, the child is the source of the relationship.

Wagtail-TreeModelAdmin is an extension of Wagtail's ModelAdmin. It is intended to be used exactly like ModelAdmin.



To use Wagtail-TreeModelAdmin you first need to define some models that will be exposed in the Wagtail Admin.

# libraryapp/

from django.db import models

class Author(models.Model):
    name = models.CharField(max_length=255)

class Book(models.Model):
    author = models.ForeignKey(Author, on_delete=models.PROTECT)
    title = models.CharField(max_length=255)

Then create the TreeModelAdmin subclasses and register the root the tree using modeladmin_register:

# libraryapp/
from wagtail.contrib.modeladmin.options import modeladmin_register

from treemodeladmin.options import TreeModelAdmin

from libraryapp.models import Author, Book

class BookModelAdmin(TreeModelAdmin):
    model = Book
    parent_field = 'author'

class AuthorModelAdmin(TreeModelAdmin):
    menu_label = 'Library'
    menu_icon = 'list-ul'
    model = Author
    child_field = 'book_set'
    child_model_admin = BookModelAdmin

Then visit the Wagtail admin. Library will be in the menu, and will give you a list of authors, and each author will have a link that will take you to their books.


Wagtail-TreeModelAdmin uses three new attributes on ModelAdmin subclasses to express parent/child relationships:

  • parent_field: The name of the Django ForeignKey on a child model.
  • child_field: The related_name on a Django ForeignKey.
  • child_model_admin

Any TreeModelAdmin subclass can specify both parent and child relationships. The root of the tree (either the TreeModelAdmin included in a ModelAdminGroup or the @modeladmin_registered TreeModelAdmin subclass) should only include child_* fields.

Getting help

Please add issues to the issue tracker.

Getting involved

General instructions on how to contribute can be found in CONTRIBUTING.


  1. TERMS
  3. CFPB Source Code Policy

Credits and references

  1. Forked from cfgov-refresh
You can’t perform that action at this time.