The Admin Site
Django comes with a complete admin site: a secure, ready-made dashboard where trusted staff can add, edit, search and delete your data. With a few lines of code, your Campus Events organisers get a working back office without you building a single form.
Step 1: Create a superuser
The admin needs a user account with full permissions. Make sure you've run migrate, then:
python manage.py createsuperuser
The suggested username comes from your computer's user name, so yours will differ. The password isn't shown as you type; that's normal. If your password is short or too common, Django warns you and asks whether to bypass validation. Choose a strong one instead.
Start the server and open http://127.0.0.1:8000/admin/. Log in, and you'll see Groups and Users, from the built-in auth app. Your Event model isn't there yet.
Step 2: Register your model
events/admin.py
from django.contrib import admin from .models import Event admin.site.register(Event)
Refresh the admin and an Events section appears. You can now add, view, edit and delete events. The admin builds the forms from your model fields, with date pickers for starts_at, checkboxes for is_free and validation for max_length. Each event is listed by its __str__, which is why defining that method matters.
Step 3: Customise the list page
A plain list of titles gets hard to use once you have hundreds of events. A ModelAdmin class controls how a model appears. Replace the simple registration with this:
events/admin.py
from django.contrib import admin
from .models import Event
@admin.register(Event)
class EventAdmin(admin.ModelAdmin):
list_display = ["title", "venue", "starts_at", "capacity", "is_free"]
list_filter = ["is_free", "venue"]
search_fields = ["title", "description", "venue"]
date_hierarchy = "starts_at"
ordering = ["starts_at"]
list_per_page = 25
| Option | Effect |
|---|---|
list_display | Columns shown in the list. Click a column heading to sort. |
list_filter | A sidebar of filters, e.g. "Is free: Yes / No". |
search_fields | Adds a search box that looks through these fields. |
date_hierarchy | Year, month and day links across the top for drilling into dates. |
ordering | Default sort order in the admin. |
list_per_page | How many rows appear on each page. |
The @admin.register(Event) decorator does the same as admin.site.register(Event, EventAdmin).
Customising the edit form
You can also control the add/edit page:
@admin.register(Event)
class EventAdmin(admin.ModelAdmin):
list_display = ["title", "venue", "starts_at", "capacity", "is_free"]
readonly_fields = ["created_at"]
fieldsets = [
(None, {"fields": ["title", "description"]}),
("When and where", {"fields": ["venue", "starts_at"]}),
("Tickets", {"fields": ["capacity", "is_free", "created_at"]}),
]
fieldsetsgroups fields under headings.readonly_fieldsshows values that can't be edited, such as the automaticcreated_at.fields(a simple list) chooses which fields appear and in what order, if you don't need headings.
Custom columns and actions
A column can come from a method. Actions let staff change many rows at once from the list page:
events/admin.py
@admin.register(Event)
class EventAdmin(admin.ModelAdmin):
list_display = ["title", "venue", "starts_at", "is_free", "size"]
actions = ["make_free"]
@admin.display(description="Size")
def size(self, obj):
return "Large" if obj.capacity >= 200 else "Small"
@admin.action(description="Mark selected events as free")
def make_free(self, request, queryset):
updated = queryset.update(is_free=True)
self.message_user(request, f"{updated} event(s) marked as free.")
Tick some events, choose "Mark selected events as free" from the Action menu and click Go. The admin also includes a built-in "Delete selected events" action, which asks for confirmation first.
Branding the admin
events/admin.py
admin.site.site_header = "Campus Events Admin" admin.site.site_title = "Campus Events" admin.site.index_title = "Manage events and users"
Who should use the admin?
The admin is a tool for trusted staff, such as the student council's events team, not for the public. Only users with is_staff set can log in, and they only see the models their permissions allow. Your public pages, like the event list and sign-up forms, should be built with your own views and templates.
On a live site, the admin is a target for password-guessing attacks. Use strong passwords, keep superuser accounts to a minimum and consider moving it from admin/ to a less obvious path in campus/urls.py, e.g. path("staff-portal-7k/", admin.site.urls).
Registering the same model twice, e.g. with both admin.site.register(Event) and @admin.register(Event). Django raises AlreadyRegistered. Keep one registration per model.
Key points
- Create an admin account with
python manage.py createsuperuserand log in at/admin/. - Register models in
admin.pyto manage them in the admin. - A
ModelAdminclass adds columns, filters, search, fieldsets and bulk actions. - The admin is for trusted staff; build public pages with your own views.
Tip: use the ← and → keys to move between pages.
