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#
assets
Type:
Namespace
attr
(evaluated)The attribute path to apply or get the data from. For example using
foo__bar__baz
will result inyour_instance.foo.bar.baz
will be set by theapply()
function. Defaults to same as nameType:
str
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 usestr(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 givenchoice
. Default implementation will usestr(choice)
Type:
Callable[..., str]
Default:
lambda choice, **_: '%s' % choice
choice_to_optgroup
Type:
Union[Callable[..., Union[str, NoneType]], NoneType]
choices
(evaluated)Type:
Callable[..., List[Any]]
display_name
(evaluated)The text in the HTML label tag. Default:
capitalize(name).replace('_', ' ')
Type:
str
editable
(evaluated)Is this field editable.
Type:
bool
Default:
True
empty_label
(evaluated)Type:
str
Default:
---
endpoints
Type:
Namespace
errors
Type:
Errors
extra
Type:
Dict[str, Any]
extra_evaluated
Type:
Dict[str, Any]
extra_params
group
(evaluated)Type:
str
help
Type: Fragment
help_text
The help text will be grabbed from the django model if specified and available.
include
(evaluated)Type:
bool
initial
(evaluated)Initial value of the field
Type:
Any
input
Type: Fragment
iommi_style
Type:
str
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!'),
)
label
Type: Fragment
model
(evaluated)Type:
Union[Type[django.db.models.base.Model], NoneType]
model_field
Type:
Union[django.db.models.fields.Field, NoneType]
model_field_name
non_editable_input
Type: Fragment
Default:
{'call_target': <class 'iommi.fragment.Fragment'>, 'children__text': <function Field.<lambda> at 0x7fe6b33fc3b0>, 'attrs__value': <function Field.<lambda> at 0x7fe6b33fc440>, 'attrs__disabled': <function Field.<lambda> at 0x7fe6b33fc4d0>}
parse
Parse function. Default just returns the string input unchanged. This function can raise
ValueError
orValidationError
to produce a field error message.parse_empty_string_as_none
(evaluated)Type:
bool
Default:
True
parsed_data
(evaluated)Type:
Any
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,
)
)
required
(evaluated)If the field is a required field. Default:
True
Type:
bool
Default:
True
search_fields
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
template
(evaluated)Django template filename or
Template
instance for the entire row. Normally you shouldn’t need to override on this level. Prefer overridinginput__template
,label__template
orerror__template
as needed.Type:
Union[str, iommi._web_compat.Template]
write_to_instance
Callback to write value to instance. Invoked with parameters field, instance and value.
Shortcuts#
boolean
#
Defaults#
parse
iommi.form.bool_parse
required
False
is_boolean
True
boolean_tristate
#
Defaults#
choices
[True, False]
choice_id_formatter
lambda choice, **_: 'true' if choice else 'false'
choice_display_name_formatter
lambda choice, **_: gettext('Yes') if choice else gettext('No')
parse
iommi.form.boolean_tristate__parse
required
False
checkboxes
#
Defaults#
input__attrs__id
None
extra_evaluated__id
iommi.form.default_input_id
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
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
date
#
Defaults#
parse
iommi.form.date_parse
render_value
iommi.form.date_render_value
datetime
#
Defaults#
parse
iommi.form.datetime_parse
render_value
iommi.form.datetime_render_value
extra_evaluated__is_tz_aware
lambda **_: settings.USE_TZ
decimal
#
Defaults#
parse
iommi.form.decimal_parse
email
#
Defaults#
input__attrs__type
email
parse
iommi.form.email_parse
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
float
#
Defaults#
parse
iommi.form.float_parse
foreign_key
#
foreign_key_reverse
#
Defaults#
editable
False
display_name
lambda field, **_: capitalize(field.model_field.related_model._meta.verbose_name_plural)
help_text
None
hardcoded
#
Defaults#
template
iommi/blank.html
heading
#
Defaults#
editable
False
attr
None
image
#
Defaults#
template
iommi/form/image_row.html
info
#
Shortcut to create an info entry.
Defaults#
editable
False
attr
None
integer
#
Defaults#
parse
iommi.form.int_parse
many_to_many
#
many_to_many_reverse
#
Defaults#
display_name
lambda field, **_: capitalize(field.model_field.remote_field.model._meta.verbose_name_plural)
help_text
None
multi_choice
#
Defaults#
is_list
True
multi_choice_queryset
#
Defaults#
is_list
True
non_rendered
#
Defaults#
template
<iommi._web_compat.Template object at 0x7fe6b340e090>
editable
False
number
#
password
#
Defaults#
input__attrs__type
password
phone_number
#
Defaults#
is_valid
iommi.form.phone_number_is_valid
radio
#
Defaults#
input__attrs__id
None
extra_evaluated__id
iommi.form.default_input_id
text
#
Defaults#
input__attrs__type
text
textarea
#
Defaults#
input__tag
textarea
input__attrs__type
None
input__attrs__value
None
input__attrs__readonly
lambda field, **_: True if field.editable is False else None
input__children__text
lambda field, **_: field.rendered_value
time
#
Defaults#
parse
iommi.form.time_parse
render_value
iommi.form.time_render_value
url
#
Defaults#
input__attrs__type
url
parse
iommi.form.url_parse