From 8778695e951e6efbe5913eefbf1464a24bdc019e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20P=C3=A9pin?= Date: Sun, 22 Dec 2019 23:37:20 +0100 Subject: [PATCH] Add some more documentation in events.models --- events/models.py | 51 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 42 insertions(+), 9 deletions(-) diff --git a/events/models.py b/events/models.py index 5838e513..e334784e 100644 --- a/events/models.py +++ b/events/models.py @@ -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.db import models from django.utils.translation import gettext_lazy as _ @@ -29,12 +59,11 @@ class Event(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 - is when the participants have the choice between different meal types (e.g. vegan / - vegetarian / no pork / with meat). In this case, the "meal type" is an `Option` and - the three alternatives are `OptionChoice`s. + The available choices are given by `OptionChoice`s (see below). A typical use-case + is for events where the participants have the choice between different menus (e.g. + vegan / vegetarian / without-pork / whatever). """ event = models.ForeignKey(Event, on_delete=models.CASCADE, related_name="options") @@ -50,7 +79,7 @@ class Option(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") choice = models.CharField(_("choix"), max_length=200) @@ -64,11 +93,11 @@ class OptionChoice(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. - Typical examples are "remarks" fields (of type LONGTEXT) or more specific questions - such as "emergency contact". + Typical examples are "remarks" fields (of type LONGTEXT) or more specific fields + such as "emergency contact" (of type SHORTTEXT probably?). """ LONGTEXT = "longtext" @@ -87,6 +116,8 @@ class ExtraField(models.Model): class ExtraFieldContent(models.Model): + """Value entered in an extra field.""" + field = models.ForeignKey(ExtraField, on_delete=models.CASCADE) registration = models.ForeignKey( "Registration", on_delete=models.CASCADE, related_name="extra_info" @@ -106,6 +137,8 @@ class ExtraFieldContent(models.Model): class Registration(models.Model): + """A user registration to an event.""" + event = models.ForeignKey(Event, on_delete=models.CASCADE) user = models.ForeignKey(User, on_delete=models.CASCADE) options_choices = models.ManyToManyField(OptionChoice)