Field ===== Base class: :doc:`Part` Class that describes a field, i.e. what input controls to render, the label, etc. See :doc:`Form` for more complete examples. The life cycle of the data is: 1. `raw_data`: will be set if the corresponding key is present in the HTTP request 2. `parsed_data`: set if parsing is successful, which only happens if the previous step succeeded 3. `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: .. code-block:: python Field(attrs__id=lambda form, field: 'my_id_%s' % field._name) Refinable members ----------------- `after`     (:ref:`evaluated `) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Set the order of columns, see the `howto `_ for an example. Type: `Union[int, str]` See :ref:`after ` Cookbook: :ref:`field-order` `assets` ^^^^^^^^ Type: `Namespace` See :ref:`assets ` `attr`     (:ref:`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 :ref:`attr ` `attrs`     (:ref:`evaluated `) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A dict containing any custom html attributes to be sent to the `input__template`. Type: :doc:`Attrs` See :ref:`attributes ` Cookbook: :ref:`freetext-column` `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`     (:ref:`evaluated `) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Type: `Callable[..., List[Any]]` Cookbook: :ref:`dependent-fields2` :ref:`dependent-fields` `display_name`     (:ref:`evaluated `) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The text in the HTML label tag. Default: `capitalize(name).replace('_', ' ')` Type: `str` See :ref:`name ` `editable`     (:ref:`evaluated `) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Is this field editable. Type: `bool` Default: `True` Cookbook: :ref:`field-non-editable` :ref:`create-or-edit-forms` :ref:`non-rendered-field` `empty_label`     (:ref:`evaluated `) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Type: `str` Default: `---` `endpoints` ^^^^^^^^^^^ Type: `Namespace` See :ref:`endpoints ` `errors` ^^^^^^^^ Type: `Errors` `extra` ^^^^^^^ Type: `Dict[str, Any]` See :ref:`extra ` `extra_evaluated` ^^^^^^^^^^^^^^^^^ Type: `Dict[str, Any]` See :ref:`extra ` `extra_params` ^^^^^^^^^^^^^^ See :ref:`extra_params ` `group`     (:ref:`evaluated `) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Type: `str` Cookbook: :ref:`group-fields` `help` ^^^^^^ Type: :doc:`Fragment` `help_text` ^^^^^^^^^^^ The help text will be grabbed from the django model if specified and available. `include`     (:ref:`evaluated `) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Type: `bool` See :ref:`include ` Cookbook: :ref:`show-fields` :ref:`include-exclude-fields` :ref:`field-reverse-m2m` `initial`     (:ref:`evaluated `) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Initial value of the field Type: `Any` Cookbook: :ref:`field-initial-value` :ref:`non-rendered-field` `input` ^^^^^^^ Type: :doc:`Fragment` Cookbook: :ref:`field-input-template` `iommi_style` ^^^^^^^^^^^^^ Type: `str` See :ref:`iommi_style ` `is_boolean`     (:ref:`evaluated `) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Type: `bool` Default: `False` `is_list`     (:ref:`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. .. code-block:: python form = Form.create( auto__model=Artist, fields__name__is_valid=lambda parsed_data, **_: (parsed_data.startswith('H'), 'Must start with H!'), ) .. raw:: html
▼ Hide result
Cookbook: :ref:`validate-multiple-fields-together` :ref:`custom-validator` `label` ^^^^^^^ Type: :doc:`Fragment` `model`     (:ref:`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: :doc:`Fragment` Default: `{'call_target': , 'children__text': at 0x73715aba8e00>, 'attrs__value': at 0x73715aba8ea0>}` `parse` ^^^^^^^ Parse function. Default just returns the string input unchanged. This function can raise `ValueError` or `ValidationError` to produce a field error message. Cookbook: :ref:`supply-custom-parser-field` `parse_empty_string_as_none`     (:ref:`evaluated `) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Type: `bool` Default: `True` `parsed_data`     (:ref:`evaluated `) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Type: `Any` Cookbook: :ref:`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`. .. code-block:: python sentinel = '!!custom!!' form = Form( fields__foo=Field( initial='not sentinel value', render_value=lambda form, field, value, **_: sentinel, ) ) .. raw:: html
▼ Hide result
`render_value_on_error` ^^^^^^^^^^^^^^^^^^^^^^^ `required`     (:ref:`evaluated `) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If the field is a required field. Default: `True` Type: `bool` Default: `True` Cookbook: :ref:`field-required` `search_fields` ^^^^^^^^^^^^^^^ Cookbook: :ref:`field-search-fields` `strip_input`     (:ref:`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`     (:ref:`evaluated `) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Type: `str` Default: `div` See :ref:`tag ` `template`     (:ref:`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 :ref:`template