Field¶

Base class: Part

Class that describes a field, i.e. what input controls to render, the label, etc.

See Form for more complete examples.

The life cycle of the data is:

raw_data: will be set if the corresponding key is present in the HTTP request

parsed_data: set if parsing is successful, which only happens if the previous step succeeded

value: set if validation is successful, which only happens if the previous step succeeded

Note that, in addition to the parameters with the defined behavior below, you can pass in any keyword argument you need yourself, including callables that conform to the protocol, and they will be added and evaluated as members.

All these parameters can be callables, and if they are, will be evaluated with the keyword arguments form and field. The only exceptions are is_valid (which gets form, field and parsed_data), render_value (which takes form, field and value) and parse (which gets form, field, string_value). Example of using a lambda to specify a value:

Field(attrs__id=lambda form, field: 'my_id_%s' % field._name)

Refinable members¶

`after` (evaluated)¶

Set the order of columns, see the howto for an example.

Type: Union[int, str]

See after

Cookbook:: How do I change the order of the fields?

`assets`¶

Type: Namespace

See assets

`attr` (evaluated)¶

The attribute path to apply or get the data from. For example using foo__bar__baz will result in your_instance.foo.bar.baz will be set by the apply() function. Setting this to None will mean no attribute is read or written by apply(). Defaults to same as name.

Type: str

See attr

`attrs` (evaluated)¶

A dict containing any custom html attributes to be sent to the input__template.

Type: Attrs

See attributes

Cookbook:: How do I make a freetext search field?

`choice_display_name_formatter`¶

Callback given the keyword argument choice in addition to standard parameters, to obtain the display name representing a given choice to the end user. Default implementation will use str(choice)

Type: Callable[..., str]

Default: lambda choice, **_: '%s' % choice

`choice_id_formatter`¶

Callback given the keyword argument choice in addition to standard parameters, to obtain the string value to represent the identity of a given choice. Default implementation will use str(choice)

Type: Callable[..., str]

Default: lambda choice, **_: '%s' % choice

`choice_to_optgroup`¶

Type: Optional[Callable[..., Optional[str]]]

`choices` (evaluated)¶

Type: Callable[..., List[Any]]

Cookbook:

How do I make a field that depends on the choice in another field?

How do I make a fields choices depend on another field?

`display_name` (evaluated)¶

The text in the HTML label tag. Default: capitalize(name).replace('_', ' ')

Type: str

See name

`editable` (evaluated)¶

Is this field editable.

Type: bool

Default: True

Cookbook:

How do I make a create or edit form?

How do I set an initial value on a field that is not in the form?

How do I make a field non-editable?

`empty_label` (evaluated)¶

Type: str

Default: ---

`endpoints`¶

Type: Namespace

See endpoints

`errors`¶

Type: Errors

`extra`¶

Type: Dict[str, Any]

See extra

`extra_evaluated`¶

Type: Dict[str, Any]

See extra

`extra_params`¶

See extra_params

`group` (evaluated)¶

Type: str

Cookbook:: How do I group fields?

`help`¶

Type: Fragment

`help_text`¶

The help text will be grabbed from the django model if specified and available.

`include` (evaluated)¶

Type: bool

See include

Cookbook:

How do I specify which fields to show?

How do I say which fields to include when creating a form from a model?

How do I show a reverse many-to-many relationship?

`initial` (evaluated)¶

Initial value of the field

Type: Any

Cookbook:

How do I set an initial value on a field that is not in the form?

How do I supply a custom initial value?

`input`¶

Type: Fragment

Cookbook:: How do I override rendering of the input field?

`iommi_style`¶

Type: str

See iommi_style

`is_boolean` (evaluated)¶

Type: bool

Default: False

`is_list` (evaluated)¶

Interpret request data as a list (can NOT be a callable). Default: False`

Type: bool

Default: False

`is_valid`¶

Validation function. Should return a tuple of (bool, reason_for_failure_if_bool_is_false) or raise ValidationError.

form = Form.create(
    auto__model=Artist,
    fields__name__is_valid=lambda parsed_data, **_: (parsed_data.startswith('H'), 'Must start with H!'),
)

▼ Hide result

Cookbook:

How do I validate multiple fields together?

How do I supply a custom validator?

`label`¶

Type: Fragment

`model` (evaluated)¶

Type: Optional[Type[django.db.models.base.Model]]

`model_field`¶

Type: Optional[django.db.models.fields.Field]

`model_field_name`¶

`non_editable_input`¶

Type: Fragment

Default: {'call_target': <class 'iommi.fragment.Fragment'>, 'children__text': <function Field.<lambda> at 0x726dcbb34040>, 'attrs__value': <function Field.<lambda> at 0x726dcbb340e0>}

`parse`¶

Parse function. Default just returns the string input unchanged. This function can raise ValueError or ValidationError to produce a field error message.

Cookbook:: How do I supply a custom parser for a field?

`parse_empty_string_as_none` (evaluated)¶

Type: bool

Default: True

`parsed_data` (evaluated)¶

Type: Any

Cookbook:: How do I make a field non-editable?

`post_validation`¶

`raw_data`¶

Type: str

`read_from_instance`¶

Callback to retrieve value from edited instance. Invoked with parameters field and instance.

`render_value`¶

Render the parsed and validated value into a string. Default just converts to str.

sentinel = '!!custom!!'
form = Form(
    fields__foo=Field(
        initial='not sentinel value',
        render_value=lambda form, field, value, **_: sentinel,
    )
)

▼ Hide result

`render_value_on_error`¶

`required` (evaluated)¶

If the field is a required field. Default: True

Type: bool

Default: True

Cookbook:: How do I set if a field is required?

`search_fields`¶

Cookbook:: How do I specify which model fields the search of a choice_queryset use?

`strip_input` (evaluated)¶

Runs the input data through standard python .strip() before passing it to the parse function (can NOT be callable). Default: True

Type: bool

Default: True

`tag` (evaluated)¶

Type: str

Default: div: See tag

`template` (evaluated)¶

Django template filename or Template instance for the entire row. Normally you shouldn’t need to override on this level. Prefer overriding input__template, label__template or error__template as needed.

Type: Union[str, iommi._web_compat.Template]

See template

Cookbook:: How do I override rendering of an entire field?

`write_to_instance`¶

Callback to write value to instance. Invoked with parameters field, instance and value.

Shortcuts¶

`Field.boolean`¶

Defaults¶

parse
- iommi.form.bool_parse
required
- False
is_boolean
- True

`Field.boolean_tristate`¶

Parent: Field.choice

Defaults¶

choices
- [True, False]
choice_id_formatter
- lambda choice, **_: 'true' if choice else 'false'
choice_display_name_formatter
- lambda choice, **_: gettext_lazy('Yes') if choice else gettext_lazy('No')
parse
- iommi.form.boolean_tristate__parse
required
- False

`Field.checkboxes`¶

Parent: Field.multi_choice

Defaults¶

input__attrs__id
- None
extra_evaluated__id
- iommi.form.default_input_id

`Field.choice`¶

Shortcut for single choice field. If required is false it will automatically add an option first with the value ‘’ and the title ‘—’. To override that text pass in the parameter empty_label.

Defaults¶

required
- True
is_list
- False
is_valid
- iommi.form.choice_is_valid
input__attrs__multiple
- lambda field, **_: True if field.is_list else None
parse
- iommi.form.choice_parse

`Field.choice_queryset`¶

Defaults¶

parse
- iommi.form.choice_queryset__parse
choice_id_formatter
- lambda choice, **_: choice.pk
endpoints__choices__func
- iommi.form.choice_queryset__endpoint_handler
is_valid
- iommi.form.choice_queryset__is_valid
extra__filter_and_sort
- iommi.form.choice_queryset__extra__filter_and_sort
extra__model_from_choices
- iommi.form.choice_queryset__extra__model_from_choices

`Field.date`¶

Defaults¶

parse
- iommi.form.date_parse
render_value
- iommi.form.date_render_value

`Field.datetime`¶

Defaults¶

parse
- iommi.form.datetime_parse
render_value
- iommi.form.datetime_render_value
extra_evaluated__is_tz_aware
- lambda **_: settings.USE_TZ

`Field.decimal`¶

Parent: Field.number

Defaults¶

parse
- iommi.form.decimal_parse

`Field.duration`¶

Parent: Field.text

Defaults¶

parse
- iommi.form.duration_parse
render_value
- iommi.form.duration_render_value

`Field.email`¶

Defaults¶

input__attrs__type
- email
parse
- iommi.form.email_parse

`Field.file`¶

Defaults¶

input__attrs__type
- file
raw_data
- iommi.form.file__raw_data
write_to_instance
- iommi.form.file_write_to_instance
extra__django_related_field
- True

`Field.float`¶

Parent: Field.number

Defaults¶

parse
- iommi.form.float_parse

`Field.foreign_key`¶

`Field.foreign_key_reverse`¶

Defaults¶

editable
- False
display_name
- lambda field, **_: capitalize(field.model_field.related_model._meta.verbose_name_plural)
help_text
- None

`Field.heading`¶

Defaults¶

editable
- False
attr
- None

`Field.hidden`¶

Defaults¶

input__attrs__type
- hidden
attrs__style__display
- none

Cookbook:: How do I create a hidden field?

`Field.image`¶

Parent: Field.file

Defaults¶

template
- iommi/form/image_row.html

`Field.info`¶

Shortcut to create an info entry.

Defaults¶

editable
- False
attr
- None

`Field.integer`¶

Parent: Field.number

Defaults¶

parse
- iommi.form.int_parse

`Field.many_to_many`¶

`Field.many_to_many_reverse`¶

Defaults¶

display_name
- lambda field, **_: capitalize(field.model_field.remote_field.model._meta.verbose_name_plural)
help_text
- None

`Field.multi_choice`¶

Parent: Field.choice

Defaults¶

is_list
- True

`Field.multi_choice_queryset`¶

Defaults¶

is_list
- True

`Field.non_rendered`¶

Defaults¶

template
- <iommi._web_compat.Template object at 0x726dcb93d5d0>
editable
- False

Cookbook:: How do I set an initial value on a field that is not in the form?

`Field.number`¶

`Field.password`¶

Defaults¶

input__attrs__type
- password
render_value
- lambda **_: ''
render_value_on_error
- lambda **_: ''

`Field.phone_number`¶

Defaults¶

is_valid
- iommi.form.phone_number_is_valid

`Field.radio`¶

Parent: Field.choice

Defaults¶

input__attrs__id
- None
extra_evaluated__id
- iommi.form.default_input_id

`Field.text`¶

Defaults¶

input__attrs__type
- text

`Field.textarea`¶

Defaults¶

input__tag
- textarea
input__attrs__type
- None
input__attrs__value
- None
input__children__text
- lambda field, **_: field.rendered_value

`Field.time`¶

Defaults¶

parse
- iommi.form.time_parse
render_value
- iommi.form.time_render_value

`Field.url`¶

Defaults¶

input__attrs__type
- url
parse
- iommi.form.url_parse

Field¶

Refinable members¶

after (evaluated)¶

assets¶

attr (evaluated)¶

attrs (evaluated)¶

choice_display_name_formatter¶

choice_id_formatter¶

choice_to_optgroup¶

choices (evaluated)¶

display_name (evaluated)¶

editable (evaluated)¶

empty_label (evaluated)¶

endpoints¶

errors¶

extra¶

extra_evaluated¶

extra_params¶

group (evaluated)¶

help¶

help_text¶

include (evaluated)¶

initial (evaluated)¶

input¶

iommi_style¶

is_boolean (evaluated)¶

is_list (evaluated)¶

is_valid¶

label¶

model (evaluated)¶

model_field¶

model_field_name¶

non_editable_input¶

parse¶

parse_empty_string_as_none (evaluated)¶

parsed_data (evaluated)¶

post_validation¶

raw_data¶

read_from_instance¶

render_value¶

render_value_on_error¶

required (evaluated)¶

search_fields¶

strip_input (evaluated)¶

tag (evaluated)¶

template (evaluated)¶

write_to_instance¶

Shortcuts¶

Field.boolean¶

Defaults¶

Field.boolean_tristate¶

Defaults¶

Field.checkboxes¶

Defaults¶

Field.choice¶

Defaults¶

Field.choice_queryset¶

Defaults¶

Field.date¶

Defaults¶

Field.datetime¶

Defaults¶

Field.decimal¶

Defaults¶

Field.duration¶

Defaults¶

Field.email¶

Defaults¶

Field.file¶

Defaults¶

Field.float¶

Defaults¶

Field.foreign_key¶

Field.foreign_key_reverse¶

Defaults¶

Field.heading¶

Defaults¶

Field.hidden¶

Defaults¶

Field.image¶

`after` (evaluated)¶

`assets`¶

`attr` (evaluated)¶

`attrs` (evaluated)¶

`choice_display_name_formatter`¶

`choice_id_formatter`¶

`choice_to_optgroup`¶

`choices` (evaluated)¶

`display_name` (evaluated)¶

`editable` (evaluated)¶

`empty_label` (evaluated)¶

`endpoints`¶

`errors`¶

`extra`¶

`extra_evaluated`¶

`extra_params`¶

`group` (evaluated)¶

`help`¶

`help_text`¶

`include` (evaluated)¶

`initial` (evaluated)¶

`input`¶

`iommi_style`¶

`is_boolean` (evaluated)¶

`is_list` (evaluated)¶

`is_valid`¶

`label`¶

`model` (evaluated)¶

`model_field`¶

`model_field_name`¶

`non_editable_input`¶

`parse`¶

`parse_empty_string_as_none` (evaluated)¶

`parsed_data` (evaluated)¶

`post_validation`¶

`raw_data`¶

`read_from_instance`¶

`render_value`¶

`render_value_on_error`¶

`required` (evaluated)¶

`search_fields`¶

`strip_input` (evaluated)¶

`tag` (evaluated)¶

`template` (evaluated)¶

`write_to_instance`¶

`Field.boolean`¶

`Field.boolean_tristate`¶

`Field.checkboxes`¶

`Field.choice`¶

`Field.choice_queryset`¶

`Field.date`¶

`Field.datetime`¶

`Field.decimal`¶

`Field.duration`¶

`Field.email`¶

`Field.file`¶

`Field.float`¶

`Field.foreign_key`¶

`Field.foreign_key_reverse`¶

`Field.heading`¶

`Field.hidden`¶

`Field.image`¶

`Field.info`¶

`Field.integer`¶

`Field.many_to_many`¶

`Field.many_to_many_reverse`¶

`Field.multi_choice`¶

`Field.multi_choice_queryset`¶

`Field.non_rendered`¶

`Field.number`¶

`Field.password`¶

`Field.phone_number`¶

`Field.radio`¶

`Field.text`¶

`Field.textarea`¶

`Field.time`¶

`Field.url`¶

`add_error`¶

`bind_from_instance`¶

`get_errors`¶