Django form field types: Widgets, options and validations

Because of the uncontrolled nature of the Internet -- with its many types of devices, browsers and user experience levels -- it creates all kinds of demands on web forms regarding the types of data they must handle, as well as endless variations of how data must be sanitized to comply with the original purpose of a web form.

When you create web forms for Django applications you rely on Django form classes, which are composed of form fields. Each Django form field is important because it dictates a small piece of functionality that eventually composes the bulk of a web form's overall behavior.

Django form fields define two types of functionality, a form field's HTML markup and its server-side validation facilities. For example, a Django form field translates into the actual HTML form markup (e.g. an <input>, <select> or <textarea> tag), the HTML markup attributes (e.g. length, whether a field can be left blank or if a field must be disabled), as well as the necessary hooks to easily perform server-side validation on a form field's data.

Django form fields define these two types of web form functionality out of necessity. Although browsers have progressed tremendously with technologies like HTML5 to provide out of the box form field validation through the HTML markup itself -- without JavaScript -- a browser is still in full control of an end user that with sufficient knowledge can bypass and feed whatever data he wants to a form. Therefore, it's standard practice to further inspect form field data once it's submitted by users to see if it complies with a form's rules, a process that's made very easy thanks to the use of Django form fields.

Table 6-2 illustrates the various Django forms fields, including: their type, the HTML they produce, their default widget and their validation behavior.

Table 6-2. Django form field types, generated HTML, default widget and validation behavior

<input type='checkbox'
...>

<select>
  <option value="1" selected="selected">
     Unknown
  </option>
  <option value="2">
     Yes
  </option>
  <option value="3">
     No
  </option>
  </select>

<input type="text" ...>

<input type="email"
...>

<input type="text" ...>

<input type="text" ...>

<input type="text" ...>

<input type="url" ...>

<input type="text" ...>

<input type="text" ...>

<select >
 <option value="directory/file_1">
   file_1
  </option>
 <option value="directory/file_2">
   file_2
 </option>
 <option value="directory/file_3">
   file_3
 </option>
</select>

<input type="file" ...>

<input type="file" ...>

<input type="text" ...>

<input type="text" ...>

<input type="text" ...>

<input type="text" ...>

<input type="text" name="_0"
...>
<input type="text" name="_1" ...>

<input type="number"
...>

<input type="number"
...>

<input type="number"
...>

<select>
 <option value="tuple1_1"
           selected="selected">
	  tuple1_2
 </option>
 <option value="tuple_2_1">
          tuple_2_2
 </option>
 <option value="tuple_3_1">
          tuple_3_2
 </option>
</select>

<select>
 <option value="tuple1_1"
           selected="selected">
	   tuple1_2
 </option>
 <option value="tuple_2_1">
           tuple_2_2
 </option>
 <option value="tuple_3_1">
           tuple_3_2
 </option>
</select>

<select multiple='multiple'>
 <option value="tuple1_1"
            selected="selected">
	    tuple1_2
 </option>
 <option value="tuple_2_1">
            tuple_2_2
 </option>
 <option value="tuple_3_1">
            tuple_3_2
 </option>
</select>

<select multiple='multiple'>
 <option value="tuple1_1"
            selected="selected">
	    tuple1_2
 </option>
 <option value="tuple_2_1">
            tuple_2_2
 </option>
 <option value="tuple_3_1">
            tuple_3_2
 </option>
</select>

As you can see in table 6-2, the Django form fields provided out-of-the-box support the generation of practically every HTML form input in existence, as well as provide the necessary server-side validation for a wide array of data types. For example, you can use the CharField() form field type to capture standard text or the more specialized EmailField() form field type to ensure the captured value is a valid email. Just as you can use ChoiceField() to generate a form list with predefined values or DateField() to enforce a form value is a valid date.

The relationship between widgets and form fields

In table 6-2 you can see that besides the actual Django form field syntax (e.g. forms.CharField(), forms.ImageField()) each form field is associated with a default widget. Django widgets for the most part go unnoticed and are often mixed together with the functionality of a form field itself (e.g. if you want an HTML text input <input type="text"..> you use forms.CharField()). However, when you require changes to the HTML produced by a form field or the way a form field's data is initially processed, you'll need to work with widgets.

To make matters a little more confusing, there are many options you specify on form fields that end up being used as part of a widget. For example, the form field forms.CharField(max_length=25) tells Django to limit a value to a maximum of 25 characters upon processing, but this same max_length option is passed to the forms.widgets.TextInput() widget to generate the HTML <input type="text" maxlength="25"...> to enforce the same rule on the browser via the HTML maxlength="25" attribute. So in this case, you can actually change the HTML output through a form field option, without even knowing about widgets!

So do you really need to work with widgets to change the HTML produced by a form field ? The answer is it depends. A lot of form fields options are automatically passed to a widget behind the scenes in effect altering the generated HTML, but make no mistake about it, it's a widget that's tasked with generating the HTML and not a form field. For cases when a form field's options can't achieve a desired HTML output, then it becomes necessary to change a form field's widget to achieve a custom HTML output.

In upcoming sections in this chapter, I'll expand on the topic of Django widgets and describe how to override and customize a Django form field's default widget. Now that you know about the existence of Django widgets and their relationship with Django form fields, I'll continue on the topic of Django form fields and explain the various Django form field options and their validation behavior.

Empty, default and predetermined values: required, initial and choices.

By default, all Django form fields are marked as required which means every field must contain a value to pass validation. The required argument is valid on all Django form fields described in table 6-2 and in addition to enforcing a value is not empty on the server-side, the HTML 5 required attribute is also assigned to a form field so a user's browser also enforce validation.

If you want to allow a field value to be left empty -- None or empty string '' -- then a field must be assigned the required=False argument.

You can also assign a default value to a field through the initial argument. The initial argument is equally valid across all Django form fields described in table 6-2 and is described in detail in the previous sub-section 'Initialize forms'.

For cases in which you don't want to allow a user the ability to introduce open-ended values for a field you can restrict a field's values to a predetermined set of values through the choices argument. If you want to use the choices attribute you must use a form field data type designed to generate an HTML <select> list such as forms.ChoiceField(), forms.MultipleChoiceField or forms.FielPathField(). The choices argument cannot be used on data types like forms.CharField() designed for open-ended input.

Limiting text values: max_length, min_length, strip and validators

Form field data types that accept text such as CharField(), EmailField() and others described in table 6-2, can accept both the max_length and min_length arguments to restrict a field's value to a maximum and minimum character length, respectively.

The strip argument is used to apply Python's strip() method -- which strips all trailing and leading whitespace -- to a field's value. The strip argument can only be used on two Django field data types, CharField() which defaults to strip=True and RegexField() which defaults to strip=False.

To apply more advanced limitation rules on fields that accept text values, see the previous sub-section on 'Validating form values' which describes validators and other techniques to limit field values.

Limiting number values: max_value, min_value, max_digits, decimal_places and validators.

Form field data types that accept numbers such as IntegerField(), DecimalField() and FloatField() can accept both the max_value and min_value arguments to restrict the upper and lower bounds of field's number value, respectively.

In addition, the DecimalField() data type which accepts more elaborate number types can use the max_digits argument to restrict the maximum number of digits in a value or the decimal_places argument to specify the maximum number of decimal places in a value.

To apply more advanced limitation rules on fields that accept number values, see the previous sub-section on 'Validating form values' which describes validators and other techniques to limit field values.

Error messages: error_messages

Every Django field data type has built-in error messages. For example, when a field data type is required and no value is added by a user, Django assigns the error message This field is required to the field, as part of a form's errors dictionary. Similarly, if a field data type uses the max_length argument and the value provided by a user exceeds this threshold, Django creates the error message Ensure this value has at most X characters (it has X).

As described earlier in listing 6-18, Django error messages are typically given a message error code in addition to the error message itself. And it's these message error codes which are used to assign custom messages via the error_messages argument.

The error_messages argument expects a dictionary where each key is the message error code and its value a custom error message. For example, to provide a custom message for the required code you would use the syntax forms.CharField(error_messages={"required":"Please, pretty please provide a comment"}).Similarly, if you expect a form field to violate its max_length value, you would assign a custom error message through the max_length code (e.g. error_messages={"max_length":"This value exceeds its max length value"}).

Error codes generally map directly to the rule they violate (e.g. if a forms.IntegerField violates its max_value, Django uses the max_value code to assign a default error message, which you can override by using this code). However, there are over two dozen built-in error message codes (e.g. 'missing', 'contradiction') some of which are not too obvious. For example, a forms.ImageField can generate the error message 'Upload a valid image. The file you uploaded was either not an image or a corrupted image.', which uses the 'invalid_image' error code, meaning that to override this default error message you would need to know the error code beforehand to declare it as part of error_messages.

For the most part, customizing error messages for some of the more esoteric error codes is rarely needed. But if you're having trouble customizing error messages for a given field because you can't determine its error code, a little logging debugging on a form errors dictionary (e.g. form.errors.as_json() or some of the other methods in table 6-1) can quickly net you a form's error codes to override the messages with the error_messages argument.

Field layout values: label, label_suffix, help_text

When you output a form field in a template besides the essential HTML form field markup (e.g. <input type="text">) it's almost always accompanied by a human-friendly descriptor to indicate what a field is for (e.g. Email: <input type="text">). This human-friendly descriptor is called a label and by default in Django it's assigned the same value as the field name.

To customize a form field's label you can use the label argument. For example, to provide a more descriptive label for a field named email you can use the syntax email = EmailField(label="Please provide your email"). By default, all labels on a form are accompanied by the : symbol which functions as a suffix. You can further customize the output of field labels with the label_suffix argument on individual form fields or the form instance itself.

For example, the syntax email = EmailField(label_suffix='-->') overrides the default suffix label on the email field for the --> symbol.

In certain circumstances it can be helpful to add more explicit instructions to a form field, for such cases you can use the help_text argument. Depending on the template layout you use, the help_text value is added right next to the HTML form field markup.

For example, the syntax comment = CharField(help_text="Please be as specific as possible to receive a quick response") generates the given html_text value right next to the comment input field (e.g. Please be as specific as possible to receive a quick response <input type="text">). The next section 'Set up the layout for Django forms in templates' goes into greater detail on the use of help_text and other form layout properties.