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

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.

HTML <form> and fields

But if you haven't worked with HTML forms before, then you actually have a whole lot of HTML you will need to learn from scratch: how the <form> ....</form> tag works, and how fields and labels and stuff works, and "input" and "textarea" and "submit", and how tag attributes such as "disabled" or "required" work.

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.


Go on to: Troggle: updating Django
Return to: Troggle programmers' guide
Troggle index: Index of all troggle documents