Model Forms
A ModelForm builds a form automatically from a model. Instead of repeating every field and its rules, you tell Django which model and fields to use, and you get validation and a save() method that creates or updates database records for you.
Creating a ModelForm
Organisers need a page to create events. The Event model (with the fields from Model Relationships) already knows each field's type, length and whether it's required, so the form can reuse all of that:
events/forms.py
from django import forms
from django.utils import timezone
from .models import Event
class EventForm(forms.ModelForm):
class Meta:
model = Event
fields = ["title", "description", "category", "venue", "starts_at", "capacity", "is_free"]
widgets = {
"description": forms.Textarea(attrs={"rows": 4}),
"starts_at": forms.DateTimeInput(
attrs={"type": "datetime-local"}, format="%Y-%m-%dT%H:%M"
),
}
labels = {"starts_at": "Date and time"}
help_texts = {"capacity": "The maximum number of students who can attend."}
def clean_starts_at(self):
starts_at = self.cleaned_data["starts_at"]
if starts_at < timezone.now():
raise forms.ValidationError("An event can't start in the past.")
return starts_at
What Django generates from the model:
titlebecomes a required text input limited to 200 characters.descriptionis optional because the model hasblank=True.categorybecomes a drop-down listing everyCategory, using each one's__str__.capacitybecomes a number input that rejects negative values.is_freebecomes a checkbox.
The widgets option replaces the default plain text box for starts_at with the browser's date-and-time picker. The format makes existing values display correctly when editing.
Always list fields explicitly with fields = [...]. Using fields = "__all__" is allowed, but if you later add a sensitive field to the model, such as is_approved or organiser, it silently appears on the public form and users can set it themselves. Leave out fields you set in code, such as organiser.
Create and edit views
A ModelForm's save() method writes to the database and returns the object. Passing instance= switches the form from "create" to "edit".
events/views.py
from django.contrib import messages
from django.contrib.auth.decorators import login_required
from django.shortcuts import get_object_or_404, redirect, render
from .forms import EventForm
from .models import Event
@login_required
def event_create(request):
if request.method == "POST":
form = EventForm(request.POST)
if form.is_valid():
event = form.save(commit=False) # build the object, don't save yet
event.organiser = request.user # set a field the form doesn't include
event.save()
messages.success(request, "Event created.")
return redirect(event) # uses get_absolute_url()
else:
form = EventForm()
return render(request, "events/event_form.html", {"form": form})
@login_required
def event_update(request, pk):
event = get_object_or_404(Event, pk=pk)
if request.method == "POST":
form = EventForm(request.POST, instance=event)
if form.is_valid():
form.save()
messages.success(request, "Event updated.")
return redirect(event)
else:
form = EventForm(instance=event) # pre-filled with current values
return render(request, "events/event_form.html", {"form": form})
@login_required makes sure request.user is a real user; it's explained on the User Authentication page. Restricting editing to the event's own organiser is covered on the Permissions page.
events/urls.py (add to urlpatterns)
path("new/", views.event_create, name="event_create"),
path("<int:pk>/edit/", views.event_update, name="event_update"),
One template serves both views. form.instance.pk is empty for a new event:
events/templates/events/event_form.html
{% extends "base.html" %}
{% block content %}
<h1>{% if form.instance.pk %}Edit {{ form.instance.title }}{% else %}New event{% endif %}</h1>
<form method="post">
{% csrf_token %}
{{ form }}
<button type="submit">Save</button>
</form>
{% endblock %}
Understanding commit=False
form.save(commit=False) returns an unsaved model instance so you can fill in extra fields first, such as the logged-in organiser or a calculated value, and then call save() yourself.
Using commit=False on a form that includes a many-to-many field and forgetting form.save_m2m() after event.save(). The event is saved but its many-to-many links are silently lost. (Our EventForm doesn't include attendees, so it isn't needed here.)
The same thing with class-based views
Django's generic editing views wrap this whole pattern. They pair naturally with ModelForms:
events/views.py
from django.contrib.auth.mixins import LoginRequiredMixin
from django.urls import reverse_lazy
from django.views.generic import CreateView, DeleteView, UpdateView
from .forms import EventForm
from .models import Event
class EventCreateView(LoginRequiredMixin, CreateView):
model = Event
form_class = EventForm
def form_valid(self, form):
form.instance.organiser = self.request.user
return super().form_valid(form)
class EventUpdateView(LoginRequiredMixin, UpdateView):
model = Event
form_class = EventForm
class EventDeleteView(LoginRequiredMixin, DeleteView):
model = Event
success_url = reverse_lazy("events:event_list")
CreateViewandUpdateViewuse the templateevents/event_form.htmlby default, the same one as above.- After a successful save they redirect to the object's
get_absolute_url(), unless you setsuccess_url. DeleteViewshowsevents/event_confirm_delete.htmlon GET and deletes only on POST.- Use
reverse_lazy(), notreverse(), for class attributes, because URLs aren't loaded when the class is defined.
events/templates/events/event_confirm_delete.html
{% extends "base.html" %}
{% block content %}
<h1>Delete "{{ object.title }}"?</h1>
<p>This can't be undone.</p>
<form method="post">
{% csrf_token %}
<button type="submit">Yes, delete it</button>
<a href="{{ object.get_absolute_url }}">Cancel</a>
</form>
{% endblock %}
Key points
- A
ModelFormbuilds fields and validation from a model; list fields explicitly inMeta.fields. - Customise with
widgets,labels,help_textsandclean_<field>()methods. form.save()creates or, withinstance=, updates a record.save(commit=False)lets you set extra fields before saving.CreateView,UpdateViewandDeleteViewhandle the same pattern with less code.
Tip: use the ← and → keys to move between pages.
