Django Portfolio Project – Part 4 – The Admin Site

In the previous part of the series we created the model classes for the Portfolio website. In this part we’ll feed some data to the database and talk about the admin site in general.

What is the Admin Site?

The admin site is actually an application that we get out of the box when we create a Django website. It’s used to let us easily perform operations like creating, reading (viewing), updating and deleting records, so the typical CRUD operations. We’re going to use it to create the first instances of our models and then to perform the other operations on them. The admin site can be used in both development and production, in the letter mainly for our internal purposes, though. What I mean by that is that it’s not meant to be used by the final user of the app, because it’s too tightly coupled with the programmatic aspect of the application the user may not be acquainted with, but rather by the developers themselves. But it’s not a strict rule that must be obeyed at all times.

In order to use the admin site, there’s a couple things we have to take care of. First of all, we have to register the models we want to use. Next, we have to create a superuser and log in to the site. Once we’re done with that, we’ll be able to create the first instances of projects, categories and the other models.

Registering Models

There are currently four models in our website. Let’s register them now. The right place to do it is the admin.py file inside the catalog folder. Open the file and make sure it looks like this:

from django.contrib import admin
from .models import Category, Technology, Project, Link

admin.site.register(Category)
admin.site.register(Technology)
admin.site.register(Project)
admin.site.register(Link)

That’s it. Our models have been registered. Next, let’s create a superuser.

Superuser

We need to add a new superuser to the database in order to be able to log into the admin site. The superuser will have the permissions to manage all the objects. To create a new superuser, make sure you’re in the same directory as the manage.py file and run the following command:

python manage.py createsuperuser

You will need to enter some data in order to create the superuser, like username, email address and password. Speaking of the password, remember to make it at least 8 characters long. Otherwise, you’ll get a warning message. While you type in the password, you won’t see anything on your screen. The whole process of creating the superuser might look like so (provided you first enter a password that is too short):

PS D:\Projects\django_portfolio\portfolio> python manage.py createsuperuser
Username (leave blank to use 'pc'): prospero
Email address: p...s@gmail.com
Password: 
Password (again):
This password is too short. It must contain at least 8 characters.
Bypass password validation and create user anyway? [y/N]: N
Password: 
Password (again):
Superuser created successfully.

Once the superuser is added to the database, let’s restart the server:

python manage.py runserver

and enter the following address in the address bar of the browser:

http://localhost:8000/admin

We should now see the login site from which you can log into the admin site:

Enter the username and password you just created and log in:

Overview of the Admin Site

In the admin, site we can see all groups and users in the Authentication and Authorization section. We’ll talk in more detail about this section later on.

Below we can see all our models displayed by application. As we have only one application, catalog, that’s all we see.

If you click on one of the model names, you’ll navigate to the page where all records of that model are listed. Let’s click on Projects, for example:

We don’t have any records yet, so it says 0 projects, but we’ll start adding some records in a moment. Here we have also options to add new records of the Project type. Alternatively, we can add new records directly from the previous page:

Now that we know how to add new records, let’s actually add some. To start simple, let’s add some categories first.

Adding Categories

Let’s click on the Add button to add a new category:

In the page that opens fill in the data. The first category’s name is Web Projects (A) and the icon’s name is bi bi-globe (B). Don’t worry if the icon name doesn’t mean anything to you. It’s just a string used to identify the icon. Technically, it’s a Bootstrap Icons class. Next hit the Save and add another button (C) to add the other categories:

You’ll see a message after you successfully save a new category:

Here’s the full list of categories for our project:

After you enter the data for the last category, hit the SAVE button instead of the Save and add another one. You will now see all the categories you added:

Next, let’s add the technologies.

Adding Technologies

Just like we added the categories, we can add the technologies. Here’s the list of all the technologies we’re going to need:

Adding Projects

Projects are the meat of our app. There are way more fields to fill in. Let’s start with my Slug Race game that I made with Python and Kivy:

In the exact same way, I’ll add all my other projects. You can add yours, but if you want to follow along and use my projects instead, feel free to do so. You will find the images folder on Github, so just save it locally on your machine and select the respective image for each project. In the tables below, you can see the data related to the projects:

Slug Race

Forest Monsters

Extreme Vacation

CV Project

Waldo

Arched Cellar

Bacteria

Town Houses

Tunnel Animation

GUI Programming with Python and Kivy

Learn Over 400 Phrasal Verbs the Fun Way

Python Jumpstart Course

Your Panda3D Magazine

Your American English Magazine

Adding Links

Finally, let’s add the links. Here, we have to fill in the name, icon and address, but also select the project the link belongs to.

Have a look at this example:

Here are the links to add:

Project: Slug Race

1)

2)

3)

Project: Forest Monsters

1)

2)

3)

Project: Extreme Vacation

1)

Project: CV Project

1)

2)

Project: Waldo

1)

2)

Project: Arched Cellar

1)

Project: Bacteria

1)

2)

Project: Town Houses

1)

Project: Tunnel Animation

1)

2)

3)

Project: GUI Programming with Python and Kivy

1)

2)

3)

4)

5)

6)

Project: Learn Over 400 Phrasal Verbs the Fun Way

1)

2)

3)

4)

Project: Python Jumpstart Course

1)

2)

Project: Your Panda3D Magazine

1)

2)

3)

4)

Project: Your American English Magazine

1)

2)

3)

4)

If you now display all the links, they don’t look great:

It’s impossible to say which project each of them links to. We’ll make it more practical in a moment.

Updating and Deleting Objects

Now that we’ve entered all the projects, categories, technologies and links, we can easily edit (or update, in other words) them if need arises. To do that, we just click on the item we want to edit and a page will be displayed that looks almost the same as the page where we were creating them. This time, however, the title will read Change project (or category, etc.) instead of Add project, etc.:

Deleting items is easy, too. Let’s say we want to delete one or more of our projects. All we have to do is check the check box next to each of them, select Delete selected projects from the Action drop-down and hit the Go button:

Our admin site looks pretty good, but we can still improve it. Let’s customize it a bit so that it better suits our needs.

The ModelAdmin Class

All the items we’ve added so far, including the projects, categories, technologies and links, are displayed as simple lists. While this is fine with categories and technologies, because these are very simple models, it’s a bit problematic with projects, in particular, if there are many of them. You can have duplicate project names, so it wouldn’t be a bad idea to display the projects not as a simple list, but rather as a list view with some more information.

It’s even more true about the links. We just saw how difficult it is to say which projects they belong to by just looking at their names.

This is why we’ll change the way the projects and links are displayed. In order to do that, we have to define special classes that determine the way the models are displayed. They inherit from the ModelAdmin class. The classes have to be then registered with the model.

So, let’s add the two classes in the admin.py file:

from django.contrib import admin
from .models import Category, Technology, Project, Link

class ProjectAdmin(admin.ModelAdmin):
    pass

class LinkAdmin(admin.ModelAdmin):
    pass

admin.site.register(Category)
admin.site.register(Technology)
admin.site.register(Project, ProjectAdmin)
admin.site.register(Link, LinkAdmin)

In the last two lines we’ve modified the registrations by adding the new classes as the second argument. These classes are now empty, but we’ll be gradually filling them in as we proceed.

List Views

Let’s start with the projects.

The Projects List View

Let’s say, apart from the name of each project, we want to display the date of creation, the category and the technologies. We just have to pass the names of the fields to the list_display tuple in the order we want them to be displayed:

class ProjectAdmin(admin.ModelAdmin):
    list_display = ('name', 'date_added', 'category', 'display_technologies')

As you can see, it’s different for the technologies field. We can’t put it directly in the tuple because it’s a ManyToManyField and it would be too costly in terms of database access. This is why it’s not allowed in Django. Instead, we pass a method that we have yet to define in the model class, display_technologies. Here it is:

class Project(models.Model):
    ...
    def get_absolute_url(self):
        ...
    def display_technologies(self):
        """Create a string for the technologies in the admin site."""
        return ', '.join(technology.name for technology in self.technologies.all())
    
    display_technologies.short_description = 'technologies'

class Link(models.Model):
    ...

The string will just consist of all the names of the technologies separated by commas. We set short_description to whatever we want to be displayed in the header. 

This is how the projects are displayed now:

The Links List View

Next, in a similar way, let’s change the way the links are displayed. Besides the name of the link, it would be desirable to also display the project name, maybe even in the first position, followed by the project’s category and the name of the link in all uppercase to stand out.

This time, though, we’re going to display everything as a single string in one column. In order to do that, we’ll pass a method to list_display and define it in the model class.

class LinkAdmin(admin.ModelAdmin):
    list_display = ('display_link',)

We must pass a tuple to list_display, hence the comma at the end.

In the model class, we have to define the method:

class Link(models.Model):
    ...
    def __str__(self):
        ...
    def display_link(self):
        """Create a string for the link in the admin site."""
        return f'{self.project} ({self.project.category}) - {self.name.upper()}'
    
    display_link.short_description = 'link'

The links are now displayed in a much more readable way:

List Filters

The projects and links lists are now much more readable than before, but it may be still difficult to view them when they grow to tens or even hundreds of items. Fortunately, we can easily add some filtering functionality to them. We do it by adding the fields we want to be able to filter by to the list_filter tuple.

Let’s start with the links. We want to be able to filter them by name. Here’s the LinkAdmin class:

class LinkAdmin(admin.ModelAdmin):
    list_display = ('display_link',)
    list_filter = ('name',)

That’s it. Now, there is a filter box to the right where we can select our filtering criteria:

By clicking on the eye icon near the top, we can display the number of items in each category:

Let’s say we only want to see the links to Github. All we have to do is click on Github in the filter box:

All other links have been filtered out.

Next, let’s implement some filtering for the projects:

class ProjectAdmin(admin.ModelAdmin):
    list_display = ('name', 'date_added', 'category', 'display_technologies')
    list_filter = ('category', 'date_added', 'technologies')

Filtering by category, date of creation and technology will do:

This is it, as far as filtering is concerned.

Fields Layout

The detail views are by default laid out vertically, with all the fields in the order they are declared in the model. Have a look at the Project detail view:

But if you want, you can change it. It’s up to you which fields should be displayed and in which order. To this end, we use the fields list in the ModelAdmin class, in which we put just the fields we want to be displayed and in the order we want them to be displayed in. If we want some of the fields to be displayed side by side, so horizontally, we just wrap them in a pair of parentheses.

Let’s say, we want to display the fields a bit differently. date_added should precede and be on the same line as image. Here’s how to do that:

class ProjectAdmin(admin.ModelAdmin):
    list_display = ('name', 'date_added', 'category', 'display_technologies')
    list_filter = ('category', 'date_added', 'technologies')
    fields = ['name', 'description', ('date_added', 'image'), 'category', 'technologies']

Now the detail view looks like so:

Inlines

Now, when we add a project, we have to navigate to another view to add the links related to it. Wouldn’t it be more comfortable to add the links on the same page as the project itself? It sure would. And it’s not difficult to do. We just have to add the Add Link form as an inline to the Project detail view.

If we want a horizontal inline, we define a class that inherits from admin.TabularInline. If we need a vertical inline, the class must inherit from admin.StackedInline. So, first we define the inline class or classes, and then we add them to the inlines list in the ModelAdmin class:

from django.contrib import admin
from .models import Category, Technology, Project, Link

class LinkInline(admin.StackedInline):
    model = Link

class ProjectAdmin(admin.ModelAdmin):
    ...
    fields = ['name', 'description', ('date_added', 'image'), 'category', 'technologies']
    inlines = [LinkInline]

class LinkAdmin(admin.ModelAdmin):
    ...

You can now add the links directly while adding the project. The inline is displayed in the lower part of the view. There are a couple link forms to fill in, but you can use the close buttons on the right to remove them if you don’t need them. And the other way around, you can add more links by clicking the Add another Link button at the bottom:

If you open an existing project for edition, all related links will be displayed correctly:

Sections

Finally, if there are lots of elements in the detail view, we may consider creating one or more sections to group them. We use the fieldsets attribute to do that. It’s a tuple of tuples, where each inner tuple represents one section. Each section contains the title of the section and a dictionary with the fields that will sit in that section. If we don’t need a title for a section, we set it to None.

For example, in the Project detail view, we’ll create two sections, one for the name and description and the other one for the remaining fields. The second section will have the title Project Details. We can’t have both fields and fieldsets, though, so let’s comment out the former. Here’s the modified ProjectAdmin class:

class ProjectAdmin(admin.ModelAdmin):
    list_display = ('name', 'date_added', 'category', 'display_technologies')
    list_filter = ('category', 'date_added', 'technologies')
    #fields = ['name', 'description', ('date_added', 'image'), 'category', 'technologies']
    inlines = [LinkInline]
    fieldsets = (
        (None, {
            'fields': ('name', 'description')
        }),
        ('Project Details', {
            'fields': (('date_added', 'image'), 'category', 'technologies')
        }),
    )

Now we can see the two sections:

The first one doesn’t have a title, so it looks like before.

Now we have a pretty robust admin site that we can use to easily add, edit and delete categories, technologies, projects and links. In the next part of the series, we’ll create our views and templates.