Appendix B. Django Form Field Objects

This appendix is a quick reference for when you add fields to forms. The first section of this appendix discusses the different types of field objects. The second section discusses the Widget objects that translate to HTML elements. The third section discusses form field to model field mapping.

Field Objects

You can add several different types of fields to forms. The advantage of different types of fields is that the form can more closely match the data types that are put into it and validated.

The following sections describe the different types of Field objects.

BooleanField

The BooleanField is used to display an HTML checkbox input element. The following list describes the BooleanField:

• Default Widget: CheckboxInput

• Empty value: None

• Normalized value: True or False

• Validation: Does not raise a ValidationError

• Optional arguments: None

CharField

The CharField is used to display an HTML text input element. The following list describes the CharField:

• Default Widget: TextInput

• Empty value: Empty string

• Normalized value: Unicode object

• Validation: Validates max_length and min_length if they are specified

• Optional arguments: max_length, min_length

The max_length argument allows you to verify that the string is no longer than the specified value. The min_length argument allows you to specify that the string is at least the specified length.

ChoiceField

The ChoiceField is used to display an HTML single-select input element. The following list describes the ChoiceField:

• Default Widget: Select

• Empty value: Empty string

• Normalized value: Unicode object

• Validation: Validates that the value exists in the list choices

• Required argument: choices

The choices argument accepts a Python iterable object such as a list or tuple.

DateField

The DateField is used to display an HTML text input element for a date. The following list describes the DateField:

• Default Widget: TextInput

• Empty value: None

• Normalized value: Python datetime.date object

• Validation: Validates that the value is a Python date or datetime or a string formatted in a particular date format

• Optional argument: input_formats

The input_formats argument allows you to specify a list of viable formats to use when converting string values to dates.

The input_formats argument defaults to the following:

'%Y-%m-%d', '%m/%d/%Y',
'%m/%d/%y', '%b %d %Y',
'%b %d, %Y','%d %b %Y',
'%d %b, %Y', '%B %d %Y',
'%B %d, %Y', '%d %B %Y',
'%d %B, %Y'

See Appendix C, "Formatting Dates and Times," for more information about the date format strings.

DateTimeField

The DateTimeField is used to display an HTML text input element for a date. The following list describes the DateTimeField:

• Default Widget: TextInput

• Empty value: None

• Normalized value: Python datetime.datetime object

• Validation: Validates that the value is a Python date or datetime or a string formatted in a particular date format

• Optional argument: input_formats

The input_formats argument allows you to specify a list of viable formats to use when converting string values to dates and times.

The input_formats argument defaults to the following:

'%Y-%m-%d %H:%M:%S',
'%Y-%m-%d %H:%M',
'%Y-%m-%d',
'%m/%d/%Y %H:%M:%S',
'%m/%d/%Y %H:%M',
'%m/%d/%Y',
'%m/%d/%y %H:%M:%S',
'%m/%d/%y %H:%M',
'%m/%d/%y'

See Appendix C for more information about the date format strings.

DecimalField

The DecimalField is used to display an HTML text input element for a Python decimal value. The following list describes the DecimalField:

• Default Widget: TextInput

• Empty value: None

• Normalized value: Python decimal

• Validation: Validates that the value is decimal (ignores any leading or trailing white spaces)

• Optional arguments: max_value, min_value, max_digits, and decimal_places

The max_value argument allows you to specify a maximum value. The min_value argument allows you to specify a minimum value. The max_digits argument allows you to specify the total maximum digits, including before and after the decimal point. The decimal_places argument allows you to specify the maximum number of digits allowed after the decimal point.

EmailField

The EmailField is used to display an HTML text input element for an email address. The following list describes the EmailField:

• Default Widget: TextInput

• Empty value: Empty string

• Normalized value: Unicode object

• Validation: Validates that the value is a valid email address

• Optional arguments: max_length, min_length

The max_length argument allows you to verify that the string is no longer than the specified value. The min_length argument allows you to specify that the string is at least the specified length.

FileField

The FileField is used to display an HTML FileInput element for a file upload. The following list describes the FileField:

• Default Widget: FileInput

• Empty value: None

• Normalized value: UploadFile object containing the filename and content

• Validation: Validates that nonempty file data has been bound to the form

• Required arguments: filename, content

When using file fields in a form, you must remember to bind the file data to the form using the filename and content arguments.

ImageField

The ImageField is used to display an HTML FileInput element for an image file upload. The following list describes the ImageField:

• Default Widget: FileInput

• Empty value: None

• Normalized value: UploadFile object containing the filename and content

• Validation: Validates that nonempty file data has been bound to the form

• Required arguments: filename, content

When using file fields in a form, you must remember to bind the file data to the form using the filename and content arguments.

IntegerField

The IntegerField is used to display an HTML text input element for a Python integer value. The following list describes the IntegerField:

• Default Widget: TextInput

• Empty value: None

• Normalized value: Python integer

• Validation: Validates that the value is an integer (ignores any leading or trailing white spaces)

• Optional arguments: max_value, min_value

The max_value argument allows you to specify a maximum value. The min_value argument allows you to specify a minimum value.

IPAddressField

The IPAddressField is used to display an HTML text input element for an IP address. The following list describes the IPAddressField:

• Default Widget: TextInput

• Empty value: Empty string

• Normalized value: Unicode object

• Validation: Validates that the value is a valid IPv4 address

MultipleChoiceField

The MultipleChoiceField is used to display an HTML multiple-select input element. The following list describes the MultipleChoiceField:

• Default Widget: SelectMultiple

• Empty value: An empty Python list ([])

• Normalized value: A list of Unicode objects

• Validation: Validates that each value exists in the list choices

• Required arguments: choices

The choices argument is required for the ChoiceField. It accepts a Python iterable object such as a list or tuple.

NullBooleanField

The NullBooleanField is used to display an HTML boolean-select input element. The following list describes the NullBooleanField:

• Default Widget: NullBooleanSelect

• Empty value: None

• Normalized value: True, False, or None

• Validation: Does not raise a ValidationError

RegexField

The RegexField is used to display an HTML text input element that contains a regular expression. The following list describes the RegexField:

• Default Widget: TextInput

• Empty value: Empty string

• Normalized value: Unicode object

• Validation: Validates that the value matches the regex expression

• Required arguments: regex

• Optional arguments: max_length, min_length, error_message

The required regex argument allows you to specify a string or a compiled regular expression.

The max_length argument allows you to verify that the string is no longer than the specified value. The min_length argument allows you to specify that the string is at least the specified length. The error_message argument allows you to specify an error message to be returned for failed validation.

TimeField

The TimeField is used to display an HTML text input element for a Python datetime value. The following list describes the TimeField:

• Default Widget: TextInput

• Empty value: None

• Normalized value: Python datetime.time object

• Validation: Validates that the value is a Python datetime.time or a string formatted in a particular time format

• Optional arguments: input_formats

The input_formats argument allows you to specify a list of viable formats to use when converting string values to times.

The input_formats argument defaults to the following:

'%H:%M:%S',
'%H:%M'

URLField

The URLFiels is used to display an HTML text input element for an URL value. The following list describes the URLField:

• Default Widget: TextInput

• Empty value: Empty string

• Normalized value: Unicode object

• Validation: Validates that the value is a valid URL

• Optional arguments: max_length, min_length, verify_exists, validator_user_agent

The max_length argument allows you to verify that the string is no longer than the specified value. The min_length argument allows you to specify that the string is at least the specified length. The verify_exists argument allows you to specify a True/False value to turn URL existence validation on or off. The validator_user_agent argument allows you to specify a string to be used as the user agent when validating URL existence. It defaults to URL_VALIDATOR_USER_AGENT.