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 fields, 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 being 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`¶

Callback to generate the optgroup for the given choice. It will get the keyword argument choice. It should return None if the choice should not be grouped.

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 field non-editable?

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

How do I make a create or edit form?

`empty_label` (evaluated)¶

Type: str

Default: ---

`endpoints`¶

Type: Namespace

See endpoints

`errors`¶

Type: Errors

Cookbook:: How do I create a hidden field?

`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 show a reverse many-to-many relationship?

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

How do I specify which fields to show?

`initial` (evaluated)¶

Initial value of the field

Type: Any

Cookbook:

How do I supply a custom initial value?

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

`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

Toggle structure

Cookbook:

How do I supply a custom validator?

How do I validate multiple fields together?

`label`¶

Type: Fragment

`model` (evaluated)¶

Type: Optional[Type[Model]]

`model_field`¶

Type: Optional[Field]

`model_field_name`¶

`non_editable_input`¶

Type: Fragment

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

`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

Toggle structure

`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 uses?

`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, 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.

Cookbook:: How do I customize how a field value is written to the instance?

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`¶

Parent: Field.choice

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.choice_searchable`¶

Shortcut for single choice field, but with select2.

Parent: Field.choice

`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

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
input__attrs__multiple
- lambda field, **_: True if field.is_list else None
raw_data
- iommi.form.file__raw_data
write_to_instance
- iommi.form.file_write_to_instance
extra__django_related_field
- True
extra_evaluated__show_thumbs
- True
attrs__data-iommi-extended-file-field
- True
attrs__data-iommi-extended-file-with-thumbs
- lambda field, **_: field.extra_evaluated.show_thumbs
attrs__data-iommi-extended-file-thumb-width
- 100
attrs__data-iommi-extended-file-thumb-height
- 100
attrs__data-iommi-extended-file-loading-icon
- lambda **_: static('images/iommi-icons/spinner.svg')

`Field.float`¶

Parent: Field.number

Defaults¶

parse
- iommi.form.float_parse

`Field.foreign_key`¶

`Field.foreign_key_reverse`¶

Parent: Field.related_multiple

Defaults¶

editable
- False
display_name
- lambda field, **_: capitalize(field.model_field.related_model._meta.verbose_name_plural)
choices
- iommi.form.related__choices
extra__django_related_field
- True

`Field.hardcoded`¶

`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

`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`¶

Parent: Field.related_multiple

`Field.many_to_many_reverse`¶

Parent: Field.related_multiple

`Field.multi_choice`¶

Parent: Field.choice

Defaults¶

is_list
- True

`Field.multi_choice_queryset`¶

Parent: Field.choice_queryset

Defaults¶

is_list
- True

`Field.non_rendered`¶

Defaults¶

template
- <iommi._web_compat.Template object at 0x7eb20c770500>
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.choice_searchable¶

Field.date¶

Defaults¶

Field.datetime¶

Defaults¶

Field.decimal¶

Defaults¶

Field.dropfile¶

Field.dropimage¶

Field.duration¶

Defaults¶

Field.email¶

Defaults¶

Field.file¶

Defaults¶

Field.float¶

Defaults¶

Field.foreign_key¶

Field.foreign_key_reverse¶

Defaults¶

Field.hardcoded¶

Field.heading¶

`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.choice_searchable`¶

`Field.date`¶

`Field.datetime`¶

`Field.decimal`¶

`Field.dropfile`¶

`Field.dropimage`¶

`Field.duration`¶

`Field.email`¶

`Field.file`¶

`Field.float`¶

`Field.foreign_key`¶

`Field.foreign_key_reverse`¶

`Field.hardcoded`¶

`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.related`¶

`Field.related_multiple`¶

`Field.text`¶