Fields

Guide

TBD

API

class Field([kwargs])

An object that is responsible for doing validation and normalisation, or “cleaning” – for example: an EmailField makes sure its data is a valid e-mail address – and makes sure that acceptable “blank” values all have the same representation.

Arguments:

• kwargs (Object) – field options.

kwargs.required

determines if the field is required - defaults to true.

kwargs.widget

overrides the widget used to render the field - if not provided, the field’s default will be used.

kwargs.label

the label to be displayed for the field - if not provided, will be generated from the field’s name.

kwargs.initial

an initial value for the field to be used if none is specified by the field’s form.

kwargs.helpText

help text for the field.

kwargs.errorMessages

custom error messages for the field.

kwargs.showHiddenInitial

specifies if it is necessary to render a hidden widget with initial value after the widget.

kwargs.validators

list of addtional validators to use

class CharField([kwargs])

Validates that its input is a valid string.

Arguments:

• kwargs (Object) – field options additional to those specified in Field.

kwargs.maxLength

a maximum valid length for the input string.

kwargs.minLength

a minimum valid length for the input string.

class IntegerField([kwargs])

Validates that its input is a valid integer.

Arguments:

• kwargs (Object) – field options additional to those specified in Field.

kwargs.maxValue

a maximum value for the input.

kwargs.minValue

a minimum value for the input.

class FloatField([kwargs])

Validates that its input is a valid float.

Arguments:

• kwargs (Object) – field options additional to those specified in Field.

kwargs.maxValue

a maximum value for the input.

kwargs.minValue

a minimum value for the input.

class DecimalField([kwargs])

Validates that its input is a decimal number.

Arguments:

• kwargs (Object) – field options additional to those specified in Field.

kwargs.maxValue

a maximum value for the input.

kwargs.minValue

a minimum value for the input.

kwargs.maxDigits

the maximum number of digits the input may contain.

kwargs.decimalPlaces

the maximum number of decimal places the input may contain.

class BaseTemporalField([kwargs])

Base field for fields which validate that their input is a date or time.

Arguments:

• kwargs (Object) – field options additional to those specified in Field.

kwargs.inputFormats

a list of time.strptime input formats which are considered valid.

class DateField([kwargs])

Validates that its input is a date.

class TimeField([kwargs])

Validates that its input is a time.

class DateTimeField([kwargs])

Validates that its input is a date/time.

class RegexField([kwargs])

Validates that its input matches a given regular expression.

Arguments:

• regex (RegExp|String) – a regular expression.
• kwargs (Object) – field options, as specified in Field and CharField.

class EmailField([kwargs])

Validates that its input appears to be a valid e-mail address.

class FileField([kwargs])

Validates that its input is a valid uploaded file.

Arguments:

• kwargs (Object) – field options additional to those specified in Field.

kwargs.allowEmptyFile

true if empty files are allowed - defaults to false.

class ImageField([kwargs])

Validates that its input is a valid uploaded image.

Arguments:

• kwargs (Object) – field options, as specified in FileField.

class URLField([kwargs])

Validates that its input appears to be a valid URL.

class BooleanField([kwargs])

Normalises its input to a Boolean.

class NullBooleanField([kwargs])

A field whose valid values are null, true and false.

Invalid values are cleaned to null.

class ChoiceField([kwargs])

Validates that its input is one of a valid list of choices.

Arguments:

• kwargs (Object) – field options additional to those specified in Field.

kwargs.choices

a list of choices - each choice should be specified as a list containing two items; the first item is a value which should be validated against, the second item is a display value for that choice, for example:

{choices: [[1, 'One'], [2, 'Two']]}

Defaults to [].

class TypedChoiceField([kwargs])

A ChoiceField which returns a value coerced by some provided function.

Arguments:

• kwargs (Object) – field options additional to those specified in ChoiceField.

kwargs.coerce

a function which takes the String value output by ChoiceField’s clean method and coerces it to another type - defaults to a function which returns the given value unaltered.

kwargs.emptyValue

the value which should be returned if the selected value can be validly empty - defaults to ''.

class MultipleChoiceField([kwargs])

Validates that its input is one or more of a valid list of choices.

class TypedMultipleChoiceField([kwargs])

A MultipleChoiceField} which returns values coerced by some provided function.

Arguments:

• kwargs (Object) – field options additional to those specified in MultipleChoiceField.

kwargs.coerce

function which takes the String values output by MultipleChoiceField’s toJavaScript method and coerces it to another type - defaults to a function which returns the given value unaltered.

kwargs.emptyValue

the value which should be returned if the selected value can be validly empty - defaults to ''.

class FilePathField([kwargs])

Allows choosing from files inside a certain directory.

Arguments:

• path (String) – The absolute path to the directory whose contents you want listed - this directory must exist.
• kwargs (Object) – field options additional to those supplied in ChoiceField.

kwargs.match

a regular expression pattern - if provided, only files with names matching this expression will be allowed as choices.

kwargs.recursive

if true, the directory will be descended into recursively and all descendants will be listed as choices - defaults to false.

class ComboField([kwargs])

A Field whose clean() method calls multiple Field clean() methods.

Arguments:

• kwargs (Object) – field options additional to those specified in Field.

kwargs.fields

fields which will be used to perform cleaning, in the order they’re given.

class MultiValueField([kwargs])

A Field that aggregates the logic of multiple Fields.

Its clean() method takes a “decompressed” list of values, which are then cleaned into a single value according to this.fields. Each value in this list is cleaned by the corresponding field – the first value is cleaned by the first field, the second value is cleaned by the second field, etc. Once all fields are cleaned, the list of clean values is “compressed” into a single value.

Subclasses should not have to implement clean(). Instead, they must implement compress(), which takes a list of valid values and returns a “compressed” version of those values – a single value.

You’ll probably want to use this with MultiWidget.

Arguments:

• kwargs (Object) – field options additional to those supplied in Field.

kwargs.fields

a list of fields to be used to clean a “decompressed” list of values.

class SplitDateTimeField([kwargs])

A MultiValueField consisting of a DateField and a TimeField.

Arguments:

• kwargs (Object) – field options options, as specified in Field and MultiValueField.

class IPAddressField([kwargs])

Validates that its input is a valid IPv4 address.

class GenericIPAddressField([kwargs])

Validates that its input is a valid IPv4 or IPv6 address.

class SlugField([kwargs])

Validates that its input is a valid slug.