CUCC Expedition Handbook

Troggle and Django Forms

HTTP resquest/response

OK the following assumes that you already have experience in creating and using HTML forms and that you know your way around HTTP requests (GET and POST) and HTTP responses (status + body). You may have used PHP, JSP or ASP for this in the past. If you haven't, then start here.

Django Forms History

Django has several generations of quite different clever mechanisms to make creating HTML forms "easier". Yes, making them might be easier, but maintaining this opinionated stuff is a nightmare without adequately educating yourself how the architecture works. This will take time: do not hurry.

WARNING: when reading the Django documentation on Forms (unbound and bound) and ModelForms, do not get diverted into looking at Formsets or ModelFormsets. We do not use any formsets in troggle - of any kind.

Django 'Form' object

• In all our data entry webpages we use a Django Form object to work with the response that the form sends back to the server, where we have to interpret the data and make an update to the database. The form is bound to the data that the user has provided.
• In many (but not all) we use a Django Form object in a Django template to render [some or all of the] the HTML which displays the input fields for the user. An empty form can be rendered to the user using an unbound form.

This is now a hint that you need to refresh your knowledge of the Django template system. Fortunately you only need to know a tiny part of this to work with forms, basically just this idiom: {{ my_object.attribute }} and maybe also {{ my_dict.key }}
{{ my_variable }}


{% if my_variable %} ... {% endif %}

Now have a look at the Django templates for some of the forms you will already be familiar with from using them as a caver entering data, e.g. Logbook entry editing which uses the Django template logbookform.html... (This is one of those webpages where we do not use a Form object for writing the HTML, only for interpreting the results).

Hah, that was a nasty shock wasn't it? OK, most of that stuff is not the stuff which manages the data entry form. Concentrate on just the bits between the <form> ....</form> tags.

It might help you at this point to remind yourself how an ordinary webapge works, without a form. So look at a logbook entry which just displays the data and the corresponding template logbookentry.html... OK, not such a good idea: that is quite complicated. See For loop below.

HTML <form> and fields

You will also need to know about Django Widgets.

So that's enough to get you started. Now you are on your own, apart from help on the Website room of the Matrix chat and the nerd email list of course.

ModelForms

A few of our data entry pages use ModelForms, these are where the Form object is automagically created from a Model class. If you can't find where something is initialised, it is probably because it was done automatically and invisibly by instantiating a ModelForm.

For loop

In logbookentry.html you will see the Django template code {% for personlogentry in logbookentry.personlogentry_set.all %} which illustrates the for loop syntax, but also the my_object.attribute syntax, where the attribute is a one-to-many link to other Objects (instances of a Class) and has the function "_set" applied followed by the QuerySet function ".all". The effect of the for loop is to iterate through all the "personlogentry" instances referenced by the specific "logbookentry" the page is looking at.

For the relationship between LogBookEntry and PersonLogEntry click on the Class diagram on the right.