Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs for related model collections #145

Open
wants to merge 2 commits into
base: releases/1.5
Choose a base branch
from
Open

Update docs for related model collections #145

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0cf365e
update model-collections.rst
SamuelJennings Jun 27, 2024
0a3975e
Update model-collections.rst
SamuelJennings Jul 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 10 additions & 3 deletions docs/source/model-collections.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,7 @@ only stores their names.

class Team(models.Model):
name = models.CharField(verbose_name="Team name", max_length=50)
department = models.ForeignKey(Department, on_delete=models.CASCADE)
department = models.ForeignKey(Department, on_delete=models.CASCADE, related_name='teams')

class Meta:
unique_together = ['name', 'department']
Expand Down Expand Up @@ -223,7 +223,7 @@ the company, its departments and their teams as:
class DepartmentCollection(FormCollection):
min_siblings = 0
department = DepartmentForm()
teams = TeamCollection()
teams = TeamCollection() # attribute name MUST match related_name (see note below)
legend = "Departments"
add_label = "Add Department"
related_field = 'company'
Expand All @@ -242,14 +242,21 @@ the company, its departments and their teams as:

class CompanyCollection(FormCollection):
company = CompanyForm()
departments = DepartmentCollection()
department_set = DepartmentCollection() # attribute name MUST match related_name (see note below)

As we expect, we see that every Django model is represented by its form. Since we want to edit more
instances of the same model type, we somehow need a way to distinguish them. This is where the form
field named ``id`` comes into play. It is a hidden ``IntegerField`` and represents the primary key
of the model instances ``Department`` or ``Team``. Since newly created instances haven't any primary
key yet, it is marked with ``required=False`` to make it optional.

.. note:: Take care when naming related collections on a parent ``FormCollection``. The name must
match the reverse accessor of the related field. In this example, the ``related_name`` of the
department field has been set to ``'teams'``, therefore we can specify ``teams = TeamCollection()``
on the ``DepartmentCollection``. Conversely, no ``related_name`` is set on the company field
of the ``Department`` model, so we must instead specify ``department_set = DepartmentCollection()``
on the ``CompanyCollection``.

Finally, our ``CompanyCollection`` must be made editable and served by a Django view class. Here we
can use the the view class :class:`formset.views.EditCollectionView` as in the previous example.

Expand Down