Skip to content
Kuza Ndoto Academy

Model Forms

IntermediateChapter 5 · Page 18 of 234 min readUpdated 15 Nov 2026

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:

  • title becomes a required text input limited to 200 characters.
  • description is optional because the model has blank=True.
  • category becomes a drop-down listing every Category, using each one's __str__.
  • capacity becomes a number input that rejects negative values.
  • is_free becomes 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.

Warning

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.

Common mistake

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")
  • CreateView and UpdateView use the template events/event_form.html by default, the same one as above.
  • After a successful save they redirect to the object's get_absolute_url(), unless you set success_url.
  • DeleteView shows events/event_confirm_delete.html on GET and deletes only on POST.
  • Use reverse_lazy(), not reverse(), 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 ModelForm builds fields and validation from a model; list fields explicitly in Meta.fields.
  • Customise with widgets, labels, help_texts and clean_<field>() methods.
  • form.save() creates or, with instance=, updates a record.
  • save(commit=False) lets you set extra fields before saving.
  • CreateView, UpdateView and DeleteView handle the same pattern with less code.
Up next · Forms & UsersUser AuthenticationSign-up, login and logout.
→

Tip: use the ← and → keys to move between pages.