flask_admin.contrib.sqla.fields

Useful form fields for use with SQLAlchemy ORM.

class QuerySelectField(*args, **kwargs)

Will display a select drop-down field to choose between ORM results in a sqlalchemy Query. The data property actually will store/keep an ORM model instance, not the ID. Submitting a choice which is not in the query will result in a validation error.

This field only works for queries on models whose primary key column(s) have a consistent string representation. This means it mostly only works for those composed of string, unicode, and integer types. For the most part, the primary keys will be auto-detected from the model, alternately pass a one-argument callable to get_pk which can return a unique comparable key.

The query property on the field can be set from within a view to assign a query per-instance to the field. If the property is not set, the query_factory callable passed to the field constructor will be called to obtain a query.

Specify get_label to customize the label associated with each option. If a string, this is the name of an attribute on the model object to use as the label text. If a one-argument callable, this callable will be passed model instance and expected to return the label text. Otherwise, the model object’s __str__ or __unicode__ will be used.

If allow_blank is set to True, then a blank choice will be added to the top of the list. Selecting this choice will result in the data property being None. The label for this blank choice can be set by specifying the blank_text parameter.

Construct a new field.

Parameters:

• label – The label of the field.

• validators – A sequence of validators to call when validate is called.

• filters – A sequence of callable which are run by process() to filter or transform the input data. For example StringForm(filters=[str.strip, str.upper]). Note that filters are applied after processing the default and incoming data, but before validation.

• description – A description for the field, typically used for help text.

• id – An id to use for the field. A reasonable default is set by the form, and you shouldn’t need to set this manually.

• default – The default value to assign to the field, if no form or object input is provided. May be a callable.

• widget – If provided, overrides the widget used to render the field.

• render_kw (dict) – If provided, a dictionary which provides default keywords that will be given to the widget at render time.

• name – The HTML name of this field. The default value is the Python attribute name.

• _form – The form holding this field. It is passed by the form itself during construction. You should never pass this value yourself.

• _prefix – The prefix to prepend to the form name of this field, passed by the enclosing form during construction.

• _translations – A translations object providing message translations. Usually passed by the enclosing form during construction. See I18n docs for information on message translations.

• _meta – If provided, this is the ‘meta’ instance from the form. You usually don’t pass this yourself.

If _form isn’t provided, an UnboundField will be returned instead. Call its bind() method with a form instance and a name to construct the field.

iter_choices() → Iterator[tuple[Any, str | flask_babel.LazyString, bool, dict[str, Any]] | tuple[Any, str | flask_babel.LazyString, bool]]

Provides data for choice widget rendering. Must return a sequence or iterable of (value, label, selected, render_kw) tuples.

pre_validate(form: BaseForm) → None

Override if you need field-level validation. Runs before any other validators.

Parameters:

form – The form the field belongs to.

process_formdata(valuelist: list[str]) → None

Process data received over the wire from a form.

This will be called during form construction with data supplied through the formdata argument.

Parameters:

valuelist – A list of strings to process.

class QuerySelectMultipleField(*args, **kwargs)

Very similar to QuerySelectField with the difference that this will display a multiple select. The data property will hold a list with ORM model instances and will be an empty list when no value is selected.

If any of the items in the data list or submitted form data cannot be found in the query, this will result in a validation error.

Construct a new field.

Parameters:

• label – The label of the field.

• validators – A sequence of validators to call when validate is called.

• filters – A sequence of callable which are run by process() to filter or transform the input data. For example StringForm(filters=[str.strip, str.upper]). Note that filters are applied after processing the default and incoming data, but before validation.

• description – A description for the field, typically used for help text.

• id – An id to use for the field. A reasonable default is set by the form, and you shouldn’t need to set this manually.

• default – The default value to assign to the field, if no form or object input is provided. May be a callable.

• widget – If provided, overrides the widget used to render the field.

• render_kw (dict) – If provided, a dictionary which provides default keywords that will be given to the widget at render time.

• name – The HTML name of this field. The default value is the Python attribute name.

• _form – The form holding this field. It is passed by the form itself during construction. You should never pass this value yourself.

• _prefix – The prefix to prepend to the form name of this field, passed by the enclosing form during construction.

• _translations – A translations object providing message translations. Usually passed by the enclosing form during construction. See I18n docs for information on message translations.

• _meta – If provided, this is the ‘meta’ instance from the form. You usually don’t pass this yourself.

If _form isn’t provided, an UnboundField will be returned instead. Call its bind() method with a form instance and a name to construct the field.

iter_choices() → Iterator[tuple[Any, str | flask_babel.LazyString, bool, dict[str, Any]] | tuple[Any, str | flask_babel.LazyString, bool]]

Provides data for choice widget rendering. Must return a sequence or iterable of (value, label, selected, render_kw) tuples.

pre_validate(form: BaseForm) → None

Override if you need field-level validation. Runs before any other validators.

Parameters:

form – The form the field belongs to.

process_formdata(valuelist: Iterable[str]) → None

Process data received over the wire from a form.

This will be called during form construction with data supplied through the formdata argument.

Parameters:

valuelist – A list of strings to process.

class CheckboxListField(*args, **kwargs)

Alternative field for many-to-many relationships.

Can be used instead of QuerySelectMultipleField. Appears as the list of checkboxes. Example:

class MyView(ModelView):
    form_columns = (
        'languages',
    )
    form_args = {
        'languages': {
            'query_factory': Language.query,
        },
    }
    form_overrides = {
        'languages': CheckboxListField,
    }

Construct a new field.

Parameters:

• label – The label of the field.

• validators – A sequence of validators to call when validate is called.

• filters – A sequence of callable which are run by process() to filter or transform the input data. For example StringForm(filters=[str.strip, str.upper]). Note that filters are applied after processing the default and incoming data, but before validation.

• description – A description for the field, typically used for help text.

• id – An id to use for the field. A reasonable default is set by the form, and you shouldn’t need to set this manually.

• default – The default value to assign to the field, if no form or object input is provided. May be a callable.

• widget – If provided, overrides the widget used to render the field.

• render_kw (dict) – If provided, a dictionary which provides default keywords that will be given to the widget at render time.

• name – The HTML name of this field. The default value is the Python attribute name.

• _form – The form holding this field. It is passed by the form itself during construction. You should never pass this value yourself.

• _prefix – The prefix to prepend to the form name of this field, passed by the enclosing form during construction.

• _translations – A translations object providing message translations. Usually passed by the enclosing form during construction. See I18n docs for information on message translations.

• _meta – If provided, this is the ‘meta’ instance from the form. You usually don’t pass this yourself.

If _form isn’t provided, an UnboundField will be returned instead. Call its bind() method with a form instance and a name to construct the field.