Reasons to Use Django admin

In this chapter we are using the Django admin interface to demonstrate how customizable this app is. With only some basic customizations we are already able to manage our products and order data, as we have seen in the previous chapters. We are also already able to filter and search for products and orders in our system.

The Django admin interface comes with a built-in authentication and permission system. You can easily configure multiple users to be able to see and change only parts of your data. This interface also has a built-in log to track who changed what models in the database.

This app allows us to get an adequate state without much effort. In this chapter we will continue building upon the customizations that we already did by creating new views integrated in the admin interface, modifying the permissions of the users, integrating reporting functions, and customizing its look.

All of this is possible by mostly overriding the base classes, although this approach has limits. Given that, when customizing the admin interface, we are always overriding built-in behavior with additional code, it is advisable to not overcustomize it because your code will quickly become hard to read.

Another limitation of this approach is that you cannot fundamentally alter the user flow of the app. Just like the choice between class-based views and function-based views, if you spend more time overriding built-in behavior than codifying your own, customizing the admin interface is not the right approach.

In this chapter we will try to stretch this interface to its limits to achieve support for all the standard operations an e-commerce company should be able to do, or at least for the ones that our fictitious book-selling company requires.

Views in the admin interface

There are many more templates that represent specific sections of the screen of some of these views. I encourage you to explore these templates to understand their structure. You can find them in your Python virtualenv or online on GitHub¹.

Django admin interface comes with a built-in set of views, but you can add new views. You can define views both at the top level and at the model level. The new views will inherit all the security checks and URL namespacing of the correspondent admin instance. This makes it possible to add, for instance, all the reporting views to our admin instance, with the proper authorization checks in place.

In addition to all the preceding features, it is possible to have multiple Django admin interfaces running on one site, each with its own customizations. Up to this point we have used django.contrib.admin.site, which is an instance of django.contrib.admin.AdminSite, but nothing stops us from having many instances of it.

Configuring User Types and Permissions for the Company

Implementing Multiple admin interfaces for Users

That’s a lot of code! First of all, there are three instances of Django admin, one for each type of user we declared in the previous section. Each instance has a different set of models registered, depending on what is relevant for that type of user.

The Django admin sites will be color-coded. Colors are injected through some custom CSS. The owners’ and central office’s admin interfaces have also some extra views for reporting. The extra views are inserted in three steps: the actual view (orders_per_day), the URL mapping (in get_urls()), and the inclusion in the index template (index()).

Specifically to DispatchersAdminSite , we have special a version of ModelAdmin for Product and Order. DispatchersOrderAdmin overrides the get_queryset() method because the dispatch office only needs to see the orders that have been marked as paid already. On those, they only need to see the shipping address.

For anyone else other than owners, we are also limiting the ability to change the slugs because they are part of the URLs. If they were changed, Google or any other entity that links to our site would have broken links.

In the code we have seen above the index view had some extra template variables. To display those, a new template is required. We will place this file in templates/admin/index.html, and it will be a customization of a built-in admin template.

We now have the three dashboards that we want to give to our internal team. Please go ahead and open the URLs in your browser, after having logged in as a superuser. Bear in mind that the reporting section is not finished yet.

In the next section we will talk more about reporting with the Django ORM. The code was included above (orders_per_day()), but given how important it is, it deserves to be explained in its own section.

Reporting on Orders

When it comes to reporting, SQL queries tend to become a bit more complicated, using aggregate functions, GROUP BY clauses, etc. The purpose of the Django ORM is to map database rows to Model objects. It can be used to do reports, but that is not its primary function. This can lead to some difficult-to-understand ORM expressions, so be warned.

In Django, there are two classes of aggregation: one that acts on all entries in a QuerySet and another that acts on each entry of it. The first uses the aggregate() method , and the second annotate(). Another way to explain it is that aggregate() returns a Python dictionary, while annotate() returns a QuerySet where each entry is annotated with additional information.

There is an exception to this rule, and that is when the annotate() function is used with values(). In that case, annotations are not generated for each item of the QuerySet, but rather on each unique combination of the fields specified in the values() method .

When in doubt, you can see the SQL that the ORM is generating by checking the property query on any QuerySet.

The next few sections present some reports, and break down the ORM queries.

Viewing the Most Bought Products

We are going to add another view that shows what are the most bought products. Differently from orders_per_day(), we are going to do this with a bit more customization, and with integration tests, to show that you can apply the same concepts of normal views to admin views.

These are the bits of main/admin.py that we will add for this view:

from django import forms

...

class PeriodSelectForm(forms.Form):

    PERIODS = ((30, "30 days"), (60, "60 days"), (90, "90 days"))

    period = forms.TypedChoiceField(

        choices=PERIODS, coerce=int, required=True

    )

class ReportingColoredAdminSite(ColoredAdminSite):

    def get_urls(self):

        urls = super().get_urls()

        my_urls = [

            ...

            path(

                "most_bought_products/",

                self.admin_view(self.most_bought_products),

                name="most_bought_products",

            ),

        ]

        return my_urls + urls

    ...

    def most_bought_products(self, request):

        if request.method == "POST":

            form = PeriodSelectForm(request.POST)

            if form.is_valid():

                days = form.cleaned_data["period"]

                starting_day = datetime.now() - timedelta(

                    days=days

                )

             data = (

                 models.OrderLine.objects.filter(

                     order__date_added__gt=starting_day

                 )

                 .values("product__name")

                 .annotate(c=Count("id"))

             )

             logger.info(

                "most_bought_products query: %s", data.query

            )

            labels = [x["product__name"] for x in data]

            values = [x["c"] for x in data]

    else:

        form = PeriodSelectForm()

        labels = None

        values = None

    context = dict(

        self.each_context(request),

        title="Most bought products",

        form=form,

        labels=labels,

        values=values,

    )

    return TemplateResponse(

        request, "most_bought_products.html", context

    )

def index(self, request, extra_context=None):

    reporting_pages = [

            ...

            {

                "name": "Most bought products",

                "link": "most_bought_products/",

            },

        ]

        ...

As you can see, we can use forms inside this view. We created a simple form to select how far back we want the report for.

Additionally, we are going to create main/templates/most_bought_products.html:

{% extends "admin/base_site.html" %}

{% block extrahead %}

  <script

    src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.7.2/Chart.bundle.min.js"

    integrity="sha256-XF29CBwU1MWLaGEnsELogU6Y6rcc5nCkhhx89nFMIDQ="

    crossorigin="anonymous"></script>

{% endblock extrahead %}

{% block content %}

  <p>

    <form method="POST">

      {% csrf_token %}

      {{ form }}

      <input type="submit" value="Set period" />

    </form>

  </p>

  {% if labels and values %}

    <canvas id="myChart" width="900" height="400"></canvas>

    <script>

      var ctx = document.getElementById("myChart");

      var myChart = new Chart(ctx, {

        type: 'bar',

        data: {

          labels: {{ labels|safe }},

          datasets: [

            {

              label: 'No of purchases',

              backgroundColor: 'blue',

              data: {{ values|safe }}

            }

          ]

        },

        options: {

          responsive: false,

          scales: {

            yAxes: [

              {

                ticks: {

                  beginAtZero: true

                }

              }

            ]

          }

        }

      });

    </script>

  {% endif %}

{% endblock %}

The preceding template is very similar to the previous one, the only difference being that we are rendering the graph only when the form has been submitted. The selected period is needed for the query. The resulting page is shown in the Figure 7-1.

To conclude this functionality, we are going to add our first admin views tests. We will create a new file called main/tests/test_admin.py:

from django.test import TestCase

from django.urls import reverse

from main import factories

from main import models

class TestAdminViews(TestCase):

    def test_most_bought_products(self):

        products = [

            factories.ProductFactory(name="A", active=True),

            factories.ProductFactory(name="B", active=True),

            factories.ProductFactory(name="C", active=True),

        ]

        orders = factories.OrderFactory.create_batch(3)

        factories.OrderLineFactory.create_batch(

            2, order=orders[0], product=products[0]

        )

        factories.OrderLineFactory.create_batch(

            2, order=orders[0], product=products[1]

        )

        factories.OrderLineFactory.create_batch(

            2, order=orders[1], product=products[0]

        )

        factories.OrderLineFactory.create_batch(

            2, order=orders[1], product=products[2]

        )

        factories.OrderLineFactory.create_batch(

            2, order=orders[2], product=products[0]

        )

        factories.OrderLineFactory.create_batch(

            1, order=orders[2], product=products[1]

        )

        user = models.User.objects.create_superuser(

            "user2", "pw432joij"

        )

        self.client.force_login(user)

        response = self.client.post(

            reverse("admin:most_bought_products"),

            {"period": "90"},

        )

        self.assertEqual(response.status_code, 200)

        data = dict(

            zip(

               response.context["labels"],

               response.context["values"],

            )

        )

        self.assertEqual(data,  {"B": 3, "C": 2, "A": 6})

This test makes heavy use of factories to create enough data for the report to contain some useful information. Here are the new factories we added in main/factories.py:

...

class OrderLineFactory(factory.django.DjangoModelFactory):

    class Meta:

        model = models.OrderLine

class OrderFactory(factory.django.DjangoModelFactory):

    user = factory.SubFactory(UserFactory)

    class Meta:

        model = models.Order

Bulk Updates to Products

In the Django admin interface it is possible to apply actions in bulk. An example of this is deletion: from the change list view we can select multiple items and then select the delete action from the drop-down menu at the top of the table.

These are called “actions,” and it is possible to add custom actions to specific instances of ModelAdmin. We are going to add a couple to mark products as active or inactive.

As you can see, it is a very simple change. The result of this can be seen in the product list page by clicking the drop-down button on the left before the column names, as shown in Figure 3-5.

Printing Order Invoices (As PDFs)

The last thing we are going to tackle is a common occurrence for e-commerce shops: printing invoices. In Django there is no facility to generate PDFs, so we will need to install a third-party library.

There are multiple Python PDF libraries available online; in our case we will choose WeasyPrint . This library allows us to create PDFs out of HTML pages, and that is how we will start here. If you want more flexibility, perhaps you should rely on a different library.

WeasyPrint requires a couple of system libraries installed in the system: Cairo and Pango. They are both used for rendering the document. You can install those with your package manager. You also require the fonts required to render the CSS properly.

This Django view has two rendering modes, HTML and PDF. Both modes use the same invoice.html template, but in the case of PDF, WeasyPrint is used to post-process the output of the templating engine.

When generating PDFs, instead of using the normal render() call, we use the render_to_string() method and store the result in memory. The PDF library will then use this to generate the PDF body, which we will store in a temporary file. In our case, the temporary file will be deleted, but we could persist this in a FileField if we wanted to.

This is enough to have the functionality working, but it is not visible in the admin interface yet. To make it visible, we will add buttons to the change order view, as shown in Figure 7-2.

At this point, please go ahead and try to retrieve and view the PDF. If it does not generate correctly, you may have to go on the WeasyPrint forums and work out why. You will find most times that the issue is a missing dependency in your system.

Summary

This chapter was a deep dive into the Django admin interface. We saw how customizable this app can be. We also talked about the dangers of pushing this app too far: if the user flow we want to offer is different from the simple create/edit/delete approach, customizing the admin may not be worth it, and instead adding custom views outside of the admin may be better.

We also talked about reporting and how to structure ORM queries for this. Django documentation goes a lot deeper on this, and I encourage you to research it for more advanced queries.

We also covered PDF generation. In our case, this is done only for people in the back office. Some sites offer invoice generation directly available to website users. In that case, it would be easy to adapt the code in this chapter to offer it in a normal (non-admin) view.

In the next chapter we will talk about an extension of Django called Channels, and how we can use this to build a chat page to interact with our customers.