dal: django-autocomplete-light3 API

Views

Base views for autocomplete widgets.

class dal.views.BaseQuerySetView(**kwargs)

Base view to get results from a QuerySet.

get_queryset()

Filter the queryset with GET[‘q’].

get_result_label(result)

Return the label of a result.

get_result_value(result)

Return the value of a result.

has_more(context)

For widgets that have infinite-scroll feature.

class dal.views.ViewMixin

Common methods for autocomplete views.

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.

get(request, *args, **kwargs)

Wrap around get to set forwarded.

Widgets

Autocomplete widgets bases.

class dal.widgets.QuerySetSelectMixin(url=None, forward=None, *args, **kwargs)

QuerySet support for choices.

filter_choices_to_render(selected_choices)

Filter out un-selected choices if choices is a QuerySet.

class dal.widgets.Select(url=None, forward=None, *args, **kwargs)

Replacement for Django’s Select to render only selected choices.

class dal.widgets.SelectMultiple(url=None, forward=None, *args, **kwargs)

Replacement SelectMultiple to render only selected choices.

class dal.widgets.WidgetMixin(url=None, forward=None, *args, **kwargs)

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.

build_attrs(*args, **kwargs)

Build HTML attributes for the widget.

filter_choices_to_render(selected_choices)

Replace self.choices with selected_choices.

render_options(*args)

Django-compatibility method for option rendering.

Should only render selected options, by setting self.choices before calling the parent method.

Fields

Form fields which may create missing models.

class dal.fields.CreateModelField(queryset, empty_label=u'---------', required=True, widget=None, label=None, initial=None, help_text=u'', to_field_name=None, limit_choices_to=None, *args, **kwargs)

This field allows creating instances.

clean(value)

Try the default clean method, else create if allowed.

class dal.fields.CreateModelFieldMixin

Mixin for autocomplete form fields with create power.

create_value(value)

Create and return a model from a user value.

widget_attrs(widget)

Override to data-autocomplete-light-create to ‘true’.

class dal.fields.CreateModelMultipleField(queryset, required=True, widget=None, label=None, initial=None, help_text=u'', *args, **kwargs)

This field allows creating instances.

clean(value)

Try the default clean method, else create if allowed.

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 form 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 in Meta.fields,
• in _save_m2m() for model fields in Meta.virtual_fields and Meta.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)

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, overrides ModelField.value_from_object() which is what ModelForm uses by default,
• FormField.save_object_data(instance, name, value) should set instance attributes. Called by save() before writting the database, when instance.pk may not be set, it overrides ModelField.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 by save() after writting the database, when instance.pk is necessarely set, it overrides ModelField.save_form_data() which is normally used in this occasion for m2m and virtual model fields.

For complete rationale, see this module’s docstring.

save(commit=True)

Backport from Django 1.9+ for 1.8.

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.Select2QuerySetView(**kwargs)

List options for a Select2 widget.

class dal_select2.views.Select2ViewMixin

View mixin to render a JSON response for Select2.

get_results(context)

Return data for the ‘results’ key of the response.

render_to_response(context)

Return a JSON response in Select2 format.

Widgets

Select2 widget implementation module.

class dal_select2.widgets.ModelSelect2(url=None, forward=None, *args, **kwargs)

Select widget for QuerySet choices and Select2.

class dal_select2.widgets.ModelSelect2Multiple(url=None, forward=None, *args, **kwargs)

SelectMultiple widget for QuerySet choices and Select2.

class dal_select2.widgets.Select2WidgetMixin

Mixin for Select2 widgets.

class Media

Automatically include static files for the admin.

class dal_select2.widgets.TagSelect2(url=None, forward=None, *args, **kwargs)

ModelSelect2Multiple for tags.

build_attrs(*args, **kwargs)

Automatically set data-tags=1.

Test tools

Helpers for DAL user story based tests.

class dal_select2.test.Select2Story

Define Select2 CSS selectors.

dal_contenttypes: GenericForeignKey support

Fields

Model choice fields that take a ContentType too: for generic relations.

dal_select2_queryset_sequence: Select2 for QuerySetSequence choices

Views

View for a Select2 widget and QuerySetSequence-based business logic.

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 choicse

Views

View that supports QuerySetSequence.

Fields

Autocomplete fields for QuerySetSequence choices.

Widgets

Widget mixin that only renders selected options with QuerySetSequence.

For details about why this is required, see dal.widgets.

dal_gm2m_queryset_sequence

Fields

Form fields for using django-gm2m with QuerySetSequence.

dal_genericm2m_queryset_sequence

Fields

Autocomplete fields for django-queryset-sequence and django-generic-m2m.

dal_gm2m: django-gm2m support

Fields

GM2MField support for autocomplete fields.

dal_genericm2m: django-genericm2m support

Fields

django-generic-m2m field mixin for FutureModelForm.

dal_taggit: django-taggit support

Fields

Autocomplete form fields for django-taggit.

dal_tagulous: django-tagulous support

Fields

Tagulous TagField support.