dal: django-autocomplete-light3 API¶
Views¶
Base views for autocomplete widgets.
-
class
dal.views.
BaseQuerySetView
(**kwargs)[source]¶ Base view to get results from a QuerySet.
-
create_field
¶ Name of the field to use to create missing values. For example, if create_field=’title’, and the user types in “foo”, then the autocomplete view will propose an option ‘Create “foo”’ if it can’t find any value matching “foo”. When the user does click ‘Create “foo”’, the autocomplete script should POST to this view to create the object and get back the newly created object id.
-
model_field_name
¶ Name of the Model field to run filter against.
-
-
class
dal.views.
ViewMixin
[source]¶ Common methods for autocomplete views.
It is assumed this view will be used in conjunction with a Django
View
based class that will that will implement OPTIONS.-
forwarded
¶ Dict of field values that were forwarded from the form, may be used to filter autocompletion results based on the form state. See
linked_data
example for reference.
-
q
¶ Query string as typed by the user in the autocomplete field.
-
Widgets¶
Autocomplete widgets bases.
-
class
dal.widgets.
QuerySetSelectMixin
(url=None, forward=None, *args, **kwargs)[source]¶ QuerySet support for choices.
-
class
dal.widgets.
Select
(url=None, forward=None, *args, **kwargs)[source]¶ Replacement for Django’s Select to render only selected choices.
-
class
dal.widgets.
SelectMultiple
(url=None, forward=None, *args, **kwargs)[source]¶ Replacement SelectMultiple to render only selected choices.
-
class
dal.widgets.
WidgetMixin
(url=None, forward=None, *args, **kwargs)[source]¶ Base mixin for autocomplete widgets.
-
url
¶ Absolute URL to the autocomplete view for the widget. It can be set to a a URL name, in which case it will be reversed when the attribute is accessed.
-
forward
¶ List of field names to forward to the autocomplete view, useful to filter results using values of other fields in the form.
- Items of the list must be one of the following:
- string (e. g. “some_field”): forward a value from the field with named “some_field”;
- `dal.forward.Field(“some_field”): the same as above;
- `dal.forward.Field(“some_field”, “dst_field”): forward a value from the field with named “some_field” as “dst_field”;
- `dal.forward.Const(“some_value”, “dst_field”): forward a constant value “some_value” as “dst_field”.
-
autocomplete_function
¶ Identifier of the javascript callback that should be executed when such a widget is loaded in the DOM, either on page load or dynamically.
-
optgroups
(name, value, attrs=None)[source]¶ Exclude unselected self.choices before calling the parent method.
Used by Django>=1.10.
-
Fields¶
FutureModelForm¶
tl;dr: See FutureModelForm’s docstring.
Many apps provide new related managers to extend your django models with. For example, django-tagulous provides a TagField which abstracts an M2M relation with the Tag model, django-gm2m provides a GM2MField which abstracts an relation, django-taggit provides a TaggableManager which abstracts a relation too, django-generic-m2m provides RelatedObjectsDescriptor which abstracts a relation again.
While that works pretty well, it gets a bit complicated when it comes to encapsulating the business logic for saving such data in a form object. This is three-part problem:
- getting initial data,
- saving instance attributes,
- saving relations like reverse relations or many to many.
Django’s ModelForm calls the model field’s value_from_object()
method to
get the initial data. FutureModelForm
tries the value_from_object()
method from the form field instead, if defined. Unlike the model field, the
form field doesn’t know its name, so FutureModelForm
passes it when calling
the form field’s value_from_object()
method.
Django’s ModelForm calls the form field’s save_form_data()
in two
occasions:
- in
_post_clean()
for model fields inMeta.fields
, - in
_save_m2m()
for model fields inMeta.virtual_fields
andMeta.many_to_many
, which then operate on an instance which as a PK.
If we just added save_form_data()
to form fields like for
value_from_object()
then it would be called twice, once in
_post_clean()
and once in _save_m2m()
. Instead, FutureModelForm
would call the following methods from the form field, if defined:
save_object_data()
in_post_clean()
, to set object attributes for a given value,save_relation_data()
in_save_m2m()
, to save relations for a given value.
For example:
- a generic foreign key only sets instance attributes, its form field would do
that in
save_object_data()
, - a tag field saves relations, its form field would do that in
save_relation_data()
.
-
class
dal.forms.
FutureModelForm
(*args, **kwargs)[source]¶ ModelForm which adds extra API to form fields.
Form fields may define new methods for FutureModelForm:
FormField.value_from_object(instance, name)
should return the initial value to use in the form, overridesModelField.value_from_object()
which is what ModelForm uses by default,FormField.save_object_data(instance, name, value)
should set instance attributes. Called bysave()
before writting the database, wheninstance.pk
may not be set, it overridesModelField.save_form_data()
which is normally used in this occasion for non-m2m and non-virtual model fields.FormField.save_relation_data(instance, name, value)
should save relations required for value on the instance. Called bysave()
after writting the database, wheninstance.pk
is necessarely set, it overridesModelField.save_form_data()
which is normally used in this occasion for m2m and virtual model fields.
For complete rationale, see this module’s docstring.
dal_select2: Select2 support for DAL¶
This is a front-end module: it provides views and widgets.
Views¶
Select2 view implementation.
-
class
dal_select2.views.
Select2ListView
(**kwargs)[source]¶ Autocomplete from a list of items rather than a QuerySet.
Widgets¶
Select2 widget implementation module.
-
class
dal_select2.widgets.
ListSelect2
(url=None, forward=None, *args, **kwargs)[source]¶ Select widget for regular choices and Select2.
-
class
dal_select2.widgets.
ModelSelect2
(url=None, forward=None, *args, **kwargs)[source]¶ Select widget for QuerySet choices and Select2.
-
class
dal_select2.widgets.
ModelSelect2Multiple
(url=None, forward=None, *args, **kwargs)[source]¶ SelectMultiple widget for QuerySet choices and Select2.
-
class
dal_select2.widgets.
Select2
(url=None, forward=None, *args, **kwargs)[source]¶ Select2 widget for regular choices.
-
class
dal_select2.widgets.
Select2Multiple
(url=None, forward=None, *args, **kwargs)[source]¶ Select2Multiple widget for regular choices.
-
class
dal_select2.widgets.
Select2WidgetMixin
[source]¶ Mixin for Select2 widgets.
-
media
¶ Return JS/CSS resources for the widget.
-
Fields¶
Select2 field implementation module.
-
class
dal_select2.fields.
Select2ListChoiceField
(choice_list=None, required=True, widget=None, label=None, initial=None, help_text='', *args, **kwargs)[source]¶ Allows a list of values to be used with a ChoiceField.
Avoids unusual things that can happen if Select2ListView is used for a form where the text and value for choices are not the same.
dal_contenttypes: GenericForeignKey support¶
Fields¶
Model choice fields that take a ContentType too: for generic relations.
-
class
dal_contenttypes.fields.
ContentTypeModelFieldMixin
[source]¶ Common methods for form fields for GenericForeignKey.
ModelChoiceFieldMixin expects options to look like:
<option value="4">Model #4</option>
With a ContentType of id 3 for that model, it becomes:
<option value="3-4">Model #4</option>
-
class
dal_contenttypes.fields.
ContentTypeModelMultipleFieldMixin
[source]¶ Same as ContentTypeModelFieldMixin, but supports value list.
dal_select2_queryset_sequence: Select2 for QuerySetSequence choices¶
Views¶
View for a Select2 widget and QuerySetSequence-based business logic.
-
class
dal_select2_queryset_sequence.views.
Select2QuerySetSequenceAutoView
(**kwargs)[source]¶ Select2QuerySetSequenceAutoView class.
Filter the queryset based on the models and filter attributes of the GenericForeignKeyModelField
self.model_choice is generated from the Select2GenericForeignKeyModelField, see it’s docstring
-
class
dal_select2_queryset_sequence.views.
Select2QuerySetSequenceView
(**kwargs)[source]¶ Combines support QuerySetSequence and Select2 in a single view.
Example usage:
url( '^your-generic-autocomplete/$', autocomplete.Select2QuerySetSequenceView.as_view( queryset=autocomplete.QuerySetSequence( Group.objects.all(), TestModel.objects.all(), ) ), name='your-generic-autocomplete', )
It is compatible with the
widgets
and the fields ofdal_contenttypes
, suits generic relation autocompletes.
Wigets¶
Widgets for Select2 and QuerySetSequence.
They combine Select2WidgetMixin
and
QuerySetSequenceSelectMixin
with Django’s
Select and SelectMultiple widgets, and are meant to be used with generic model
form fields such as those in dal_contenttypes
.
dal_queryset_sequence: QuerySetSequence choices¶
Views¶
View that supports QuerySetSequence.
Fields¶
Autocomplete fields for QuerySetSequence choices.
-
class
dal_queryset_sequence.fields.
GenericForeignKeyModelField
(*args, **kwargs)[source]¶ Field that generate automatically the view for compatible widgets.
-
class
dal_queryset_sequence.fields.
QuerySetSequenceFieldMixin
[source]¶ Base methods for QuerySetSequence fields.
Widgets¶
Widget mixin that only renders selected options with QuerySetSequence.
For details about why this is required, see dal.widgets
.
-
class
dal_queryset_sequence.widgets.
QuerySetSequenceSelect
(url=None, forward=None, *args, **kwargs)[source]¶ Select widget for QuerySetSequence choices.
dal_gm2m_queryset_sequence¶
dal_genericm2m_queryset_sequence¶
dal_genericm2m: django-genericm2m support¶
Fields¶
django-generic-m2m field mixin for FutureModelForm.