Add some more documentation in events.models

This commit is contained in:
Martin Pépin 2019-12-22 23:37:20 +01:00
parent e0fd3db638
commit 8778695e95

View file

@ -1,3 +1,33 @@
"""
Event framework for GestioCOF and GestioBDS.
The events implemented in this module provide two type of customisation to event
creators (the COF and BDS staff): options and extra (text) field.
Options
-------
An option is an extra field in the registration form with a predefined list of available
choices. Any number of options can be added to an event.
For instance, a typical use-case if for events where meals are served to participants
with different possible menus, say: vegeterian / vegan / without pork / etc. This
example can be implemented with an `Option(name="menu")` and an `OptionChoice` for each
available menu.
In this example, the choice was exclusive: participants can only chose one menu. For
situations, where multiple choices can be made at the same time, use the `multi_choices`
flag.
Extra fields
------------
Extra fields can also be added to the registration form that can receive arbitrary text.
Typically, this can be a "remark" field (prefer the LONGTEXT option in this case) or
small form entries such as "phone number" or "emergency contact" (prefer the SHORTTEXT
option in this case).
"""
from django.contrib.auth import get_user_model from django.contrib.auth import get_user_model
from django.db import models from django.db import models
from django.utils.translation import gettext_lazy as _ from django.utils.translation import gettext_lazy as _
@ -29,12 +59,11 @@ class Event(models.Model):
class Option(models.Model): class Option(models.Model):
"""Event options to be selected by participants at registration. """Extra form fields with a limited set of available choices.
The possible choices are instances of `OptionChoice` (see below). A typical example The available choices are given by `OptionChoice`s (see below). A typical use-case
is when the participants have the choice between different meal types (e.g. vegan / is for events where the participants have the choice between different menus (e.g.
vegetarian / no pork / with meat). In this case, the "meal type" is an `Option` and vegan / vegetarian / without-pork / whatever).
the three alternatives are `OptionChoice`s.
""" """
event = models.ForeignKey(Event, on_delete=models.CASCADE, related_name="options") event = models.ForeignKey(Event, on_delete=models.CASCADE, related_name="options")
@ -50,7 +79,7 @@ class Option(models.Model):
class OptionChoice(models.Model): class OptionChoice(models.Model):
"""A possible choice for an event option (see Option).""" """A possible choice for an event option."""
option = models.ForeignKey(Option, on_delete=models.CASCADE, related_name="choices") option = models.ForeignKey(Option, on_delete=models.CASCADE, related_name="choices")
choice = models.CharField(_("choix"), max_length=200) choice = models.CharField(_("choix"), max_length=200)
@ -64,11 +93,11 @@ class OptionChoice(models.Model):
class ExtraField(models.Model): class ExtraField(models.Model):
"""Extra event field, for event creators. """Extra event field receiving arbitrary text.
Extra text field that can be added by event creators to the event registration form. Extra text field that can be added by event creators to the event registration form.
Typical examples are "remarks" fields (of type LONGTEXT) or more specific questions Typical examples are "remarks" fields (of type LONGTEXT) or more specific fields
such as "emergency contact". such as "emergency contact" (of type SHORTTEXT probably?).
""" """
LONGTEXT = "longtext" LONGTEXT = "longtext"
@ -87,6 +116,8 @@ class ExtraField(models.Model):
class ExtraFieldContent(models.Model): class ExtraFieldContent(models.Model):
"""Value entered in an extra field."""
field = models.ForeignKey(ExtraField, on_delete=models.CASCADE) field = models.ForeignKey(ExtraField, on_delete=models.CASCADE)
registration = models.ForeignKey( registration = models.ForeignKey(
"Registration", on_delete=models.CASCADE, related_name="extra_info" "Registration", on_delete=models.CASCADE, related_name="extra_info"
@ -106,6 +137,8 @@ class ExtraFieldContent(models.Model):
class Registration(models.Model): class Registration(models.Model):
"""A user registration to an event."""
event = models.ForeignKey(Event, on_delete=models.CASCADE) event = models.ForeignKey(Event, on_delete=models.CASCADE)
user = models.ForeignKey(User, on_delete=models.CASCADE) user = models.ForeignKey(User, on_delete=models.CASCADE)
options_choices = models.ManyToManyField(OptionChoice) options_choices = models.ManyToManyField(OptionChoice)