Forem: Lacey Williams Henschel

How to Add Django Models to the Wagtail Admin

Lacey Williams Henschel — Tue, 27 Aug 2019 15:57:14 +0000

Versions

Python 3.7
Django 2.2
Wagtail 2.6

When working with Wagtail, you might find that you're using Wagtail Page models for some of your database models, but regular Django models for others.

A built-in example of this is the Django User model. When you log into the Wagtail admin, you can see the Django User model in the Settings submenu. The User model is not a Wagtail model; it's the same User model you see in a Django project that doesn't use Wagtail. Wagtail just exposes it to the Admin for you.

We can do the same thing with our Django models: we can expose them to the Wagtail admin so we don't have to maintain two separate admin interfaces to manage our website content.

For this example, let's assume we're working with these models:

from django.db import models 


class Pizza(models.Model):

    name = models.CharField(max_length=30)
    toppings = models.ManyToManyField("Topping")


class Topping(models.Model):

    name = models.CharField(max_length=30)

Adding a single model

The Wagtail docs are pretty clear on how to accomplish this, but let's walk through the steps.

First, make sure wagtail.contrib.modeladmin is in your INSTALLED_APPS:

# settings.py 

INSTALLED_APPS = [
    ...
    "wagtail.contrib.modeladmin",
]

Next, in the same app as the model you want to expose to the Wagtail admin, add a file called wagtail_hooks.py.

# wagtail_hooks.py

from wagtail.contrib.modeladmin.options import ModelAdmin, modeladmin_register 

from .models import Pizza


class PizzaAdmin(ModelAdmin):
    model = Pizza 
    menu_label = "Pizza"  
    menu_icon = "pick" 
    menu_order = 200 
    add_to_settings_menu = False 
    exclude_from_explorer = False 
    list_display = ("name",)
    list_filter = ("toppings",)
    search_fields = ("name",)


modeladmin_register(PizzaAdmin)

Let's step through these options in the ModelAdmin class:

model: The name of the model you're adding.
menu_label: Leave this blank to use the verbose_name_plural from your model. Give it a value to specify a new label for the Wagtail menu.
menu_icon: Every menu item in the Wagtail admin has an icon, and you can specify the one you want to use. Here is a list of the available icons.
menu_order: What order you want this model to appear in. 000 is first, 100 is second, etc. Note: if you add multiple models to the admin, you won't get an error if two of them have the same menu_order; Wagtail will just pick for you.
add_to_settings_menu: Whether you want this menu item to appear in the Settings submenu in the Wagtail admin.
exclude_from_explorer: Set to True if you do not want the explorer (the search box in the admin) to return results from this model. Set to False if you do want the explorer to return results from this model. (It's confusing.)
list_display: Same as the Django admin; list the fields you want to display on the listing page for this model in the Wagtail admin.
list_filter: Same as the Django admin; supply the fields you want to use to filter in the sidebar of the Wagtail admin.
search_fields: Same as the Django admin; supply the fields that you want the explorer to use to return search results.

The final step is to register the admin class. Once you've done that and started your server, you'll be able to see your model in the Wagtail admin:

We can do the same thing with our Django models: we can expose them to the Wagtail admin so we don't have to maintain two separate admin interfaces to manage our website content.

For this example, let's assume we're working with these models:

from django.db import models 


class Pizza(models.Model):

    name = models.CharField(max_length=30)
    toppings = models.ManyToManyField("Topping")


class Topping(models.Model):

    name = models.CharField(max_length=30)

Adding a single model

The Wagtail docs are pretty clear on how to accomplish this, but let's walk through the steps.

First, make sure wagtail.contrib.modeladmin is in your INSTALLED_APPS:

# settings.py 

INSTALLED_APPS = [
    ...
    "wagtail.contrib.modeladmin",
]

Next, in the same app as the model you want to expose to the Wagtail admin, add a file called wagtail_hooks.py.

# wagtail_hooks.py

from wagtail.contrib.modeladmin.options import ModelAdmin, modeladmin_register 

from .models import Pizza


class PizzaAdmin(ModelAdmin):
    model = Pizza 
    menu_label = "Pizza"  
    menu_icon = "pick" 
    menu_order = 200 
    add_to_settings_menu = False 
    exclude_from_explorer = False 
    list_display = ("name",)
    list_filter = ("toppings",)
    search_fields = ("name",)


modeladmin_register(PizzaAdmin)

Let's step through these options in the ModelAdmin class:

model: The name of the model you're adding.
menu_label: Leave this blank to use the verbose_name_plural from your model. Give it a value to specify a new label for the Wagtail menu.
menu_icon: Every menu item in the Wagtail admin has an icon, and you can specify the one you want to use. Here is a list of the available icons.
menu_order: What order you want this model to appear in. 000 is first, 100 is second, etc. Note: if you add multiple models to the admin, you won't get an error if two of them have the same menu_order; Wagtail will just pick for you.
add_to_settings_menu: Whether you want this menu item to appear in the Settings submenu in the Wagtail admin.
exclude_from_explorer: Set to True if you do not want the explorer (the search box in the admin) to return results from this model. Set to False if you do want the explorer to return results from this model. (It's confusing.)
list_display: Same as the Django admin; list the fields you want to display on the listing page for this model in the Wagtail admin.
list_filter: Same as the Django admin; supply the fields you want to use to filter in the sidebar of the Wagtail admin.
search_fields: Same as the Django admin; supply the fields that you want the explorer to use to return search results.

The final step is to register the admin class. Once you've done that and started your server, you'll be able to see your model in the Wagtail admin:

Adding related models

In our example models, we have two models: Pizza and Toppings. We could manually add the Topping model to the Wagtail admin and have it appear just below the Pizza model. We just learned how!

But it's so closely related to the Pizza model that it might be nice if we were able to relate those two models together in a submenu, kind of like how Settings is its own submenu in the admin that contains Users, Redirects, Sites, etc.

Go back to wagtail_hooks.py:

# wagtail_hooks.py

from wagtail.contrib.modeladmin.options import (
    ModelAdmin, 
    ModelAdminGroup, 
    modeladmin_register 
)

from .models import Pizza, Topping


class PizzaAdmin(ModelAdmin):
    ...
    menu_order = 000 
    ...


class ToppingAdmin(ModelAdmin):
    model = Topping 
    menu_label = "Toppings"  
    menu_icon = "edit" 
    menu_order = 100 
    add_to_settings_menu = False 
    exclude_from_explorer = False 
    list_display = ("name",)
    search_fields = ("name",)

Relating our two models together starts off in the same way: we create a class that inherits from ModelAdmin for each model and identify the necessary attributes like model and menu_icon to control things like their listing pages and search behavior.

Then, we add a new class that inherits from ModelAdminGroup:

# wagtail_hooks.py

from wagtail.contrib.modeladmin.options import (
    ModelAdmin, 
    ModelAdminGroup, 
    modeladmin_register 
)

from .models import Pizza, Topping


class PizzaAdmin(ModelAdmin):
    ...
    menu_order = 000 
    ...


class ToppingAdmin(ModelAdmin):
    ...
    menu_order = 100 
    ... 

class PizzaGroup(ModelAdminGroup):
    menu_label = "Pizzas" 
    menu_icon = "pick"
    menu_order = 500 
    items = (PizzaAdmin, ToppingAdmin)


modeladmin_register(PizzaGroup)

In the PizzaGroup class, we have some of the same attributes:

menu_label: We set what we want this group of related models to be called in the Wagtail admin menu
menu_icon: Which icon we want to use for this menu
menu_order: Where we want this menu to appear in the sidebar, in relation to the other menu items

We also add a new attribute, items, where we list which ModelAdmin classes we want to be part of this group. In our case, we want PizzaAdmin and ToppingAdmin to be in this group, so we add those.

Note the change we made to menu_order in PizzaAdmin and ToppingAdmin: Now those are set to 000 and 100. When the ModelAdmin classes will be part of a group, set the menu_order how you want them to relate to each other, not to the other menu items in the Wagtail admin. Then set the menu_order for the ModelAdminGroup class to the proper value for the order you want it to appear in the side menu in the admin.

Then we register the whole group, instead of the ModelAdmin classes individually, to the Wagtail admin. When we reload the admin, we see this:

On the far left, there is a new menu item Pizzas that expands a submenu. The submenu contains links to the admin interfaces for Pizzas and Toppings!

Note: If you have the Django admin enabled and have your models already in the Django admin, this doesn't disable them from the regular Django admin. You are free to access your models in both the Wagtail admin and the Django admin, or at this point you can choose to remove your models from the Django admin (or disable the Django admin altogether, if you prefer).

Helpful Links

Special thanks to Jeff Triplett and Jacob Burch for their help with this post.

Using Different Read and Write Serializers in Django REST Framework

Lacey Williams Henschel — Tue, 20 Aug 2019 16:24:38 +0000

Versions:

Python 3.7
Django 2.2
Django REST Framework 3.10

On a recent project, we needed to use different serializers for GET vs. POST/PUT/PATCH requests to our Django REST Framework API. In our case, this was because the GET serializer contained a lot of nested data; for example, it contained expanded fields from other serializers to foreign-key relationships. The requests to update data via the API, though, didn't need these expanded fields.

The first way we approached using different serializers for read and update actions was to override get_serializer_class() on each viewset to decide which serializer to return depending on the action in the request. We returned the "read" serializer for list and retrieve actions, and the "update" serializer for everything else. (The full list of API actions is in the DRF codebase.) But we wound up repeating ourselves across several viewsets, so we wrote a mixin to take care of some of this work for us!

A mixin is a Python class that contains custom attributes and methods (more explanation). It's not very useful on its own, but when it's inherited into a class, that class has access to the mixin's special attributes and methods.

This was our mixin:

class ReadWriteSerializerMixin(object):
    """
    Overrides get_serializer_class to choose the read serializer
    for GET requests and the write serializer for POST requests.

    Set read_serializer_class and write_serializer_class attributes on a
    viewset. 
    """

    read_serializer_class = None
    write_serializer_class = None

    def get_serializer_class(self):        
        if self.action in ["create", "update", "partial_update", "destroy"]:
            return self.get_write_serializer_class()
        return self.get_read_serializer_class()

    def get_read_serializer_class(self):
        assert self.read_serializer_class is not None, (
            "'%s' should either include a `read_serializer_class` attribute,"
            "or override the `get_read_serializer_class()` method."
            % self.__class__.__name__
        )
        return self.read_serializer_class

    def get_write_serializer_class(self):
        assert self.write_serializer_class is not None, (
            "'%s' should either include a `write_serializer_class` attribute,"
            "or override the `get_write_serializer_class()` method."
            % self.__class__.__name__
        )
        return self.write_serializer_class

This mixin defines two new attributes, read_serializer_class and write_serializer_class. Each attribute has a corresponding method to catch the error where the mixin is being used, but those attributes haven't been set. The get_*_serializer_class() methods will raise an AssertionError if your viewset hasn't set the appropriate attribute or overridden the necessary method.

The get_serializer_class method makes the final decision on which serializer to use. For the "update" actions to the API, it returns write_serializer_class; otherwise it returns read_serializer_class.

The mixin gets used in a viewset like this:

from rest_framework import viewsets

from .mixins import ReadWriteSerializerMixin
from .models import MyModel
from .serializers import ModelReadSerializer, ModelWriteSerializer


class MyModelViewSet(ReadWriteSerializerMixin, viewsets.ModelViewSet):
    queryset = MyModel.objects.all() 
    read_serializer_class = ModelReadSerializer 
    write_serializer_class = ModelWriteSerializer

Now the viewset MyModelViewSet has access to the attributes and methods from the mixin ReadWriteSerializerMixin. This means that when a call is made to the API that uses MyModelViewSet, the get_serializer_class() method from ReadWriteSerializerMixin will automatically be called and will decide, based on the kind of API request being made, which serializer to use. If we needed to make even more granular decisions about the serializer returned (maybe we want to use a more limited serializer for a list request and one with more data in a retrieve request), then our viewset can override get_write_serializer_class() to add that logic.

Note: Custom DRF actions will contain actions that aren't part of the DRF list of accepted actions (because they are custom actions you're creating), so when you call get_serializer_class from inside your action method, it will return whatever your "default" serializer class is. In the example above, the "default" serializer is the read_serializer_class because it's what we return when we fall through the other conditional.

Depending on your action, you will want to override get_serializer_class to change your default method or explicitly account for your custom action.

Mixins are a DRY (Don't Repeat Yourself) way to add functionality that you wind up needing to use across several viewsets. We hope you get to experiment with using them soon!

Thanks to Jeff Triplett for his help with this post.