djblets.webapi.resources.mixins.forms¶
Mixins for integrating a web API resource with a form.
- class UpdateFormMixin[source]¶
A mixin for providing the ability to create and update using a form.
A WebAPIResource class using this mixin must set the
form_class
attribute to aModelForm
instance that corresponds to the model being updated.Classes using this mixin can provide methods of the form
parse_field_name_field
to do parsing of form data before it is passed to the form. Parser methods should be of the form:def parse_some_field(self, value, request, **kwargs): return some_value
These methods may return either a single value or a list of values (in the case where the corresponding field expects a list of values, such as a
ModelMultipleChoiceField
). They may also raise aValidationError
, though it’s up to the caller ofcreate_form()
to catch this and return any suitable errors.Most implementations will want to call
handle_form_request()
in their POST/PUT handlers, and override behavior with the parsing methods. Some may also want to overridesave_form()
,build_form_success_response()
, orbuild_form_error_response()
to customize behavior.- form_class = None[source]¶
The form class for updating models.
This should be a subclass of
django.forms.ModelForm
.
- property add_form_class[source]¶
The form class for creating new models.
This should be a subclass of
django.forms.ModelForm
. It defaults toform_class
.
- handle_form_request(request, data=None, files=None, instance=None, form_kwargs=None, save_kwargs=None, **kwargs)[source]¶
Handle an HTTP request for creating or updating through a form.
This can be called directly from a resource’s
create()
orupdate()
method to parse request data, create the form, and handle errors or the saving of the form.New in version 1.0.9.
- Parameters
request (django.http.HttpRequest) – The HTTP request from the client.
data (dict, optional) – The data to pass to
create_form()
.files (dict, optional) – Files to pass to the form.
instance (django.db.models.Model, optional) – An existing instance to update, if performing an HTTP PUT request.
form_kwargs (dict, optional) – Keyword arguments to pass to the form’s constructor.
save_kwargs (dict, optional) – Keyword arguments to pass to the form’s
ModelForm.save()
method.**kwargs (dict) – Keyword arguments to pass to
build_form_error_response()
,build_form_success_response()
,create_form()
,save_form()
, and any field parsing methods.
- Returns
The response to send back to the client.
- Return type
- create_form(data, request, files=None, instance=None, form_kwargs=None, **kwargs)[source]¶
Create a new form and pre-fill it with data.
Changed in version 1.0.9: The initial values for form fields are now automatically provided in the form data, if not otherwise overridden, making it easier to construct forms.
Along with this, a
ModelForm
’sfields
andexclude
lists are now factored in when populating the formw with an instance’s data.- Parameters
data (dict) – The request data to pass to the form.
request (django.http.HttpRequest) – The HTTP request.
files (dict) – Files to pass to the form.
instance (django.db.models.Model, optional) – The instance model, if it exists. If this is not
None
, fields that appear in the form class’sfields
attribute that do not appear in thedata
dict as keys will be copied from the instance.form_kwargs (dict, optional) – Additional keyword arguments to provide to the form’s constructor.
**kwargs (dict) –
Additional arguments. These will be passed to the resource’s parser methods.
This contains anything passed as keyword arguments to
handle_form_request()
.
- Returns
The form with data filled.
- Return type
- Raises
django.core.exceptions.ValidationError – A field failed validation. This is allowed to be raised by any
parse_*
methods defined on the resource.
- save_form(form, save_kwargs=None, **kwargs)[source]¶
Save and return the results of the form.
This is a simple wrapper around calling
ModelForm.save()
. It can be overridden by subclasses that need to perform additional operations on the instance or form.New in version 1.0.9.
- Parameters
form (django.forms.Form) – The form to save.
save_kwargs (dict) – Any keyword arguments to pass when saving the form.
**kwargs (dict) – Additional keyword arguments passed by the caller. This contains anything passed as keyword arguments to
handle_form_request()
.
- Returns
The saved model instance.
- Return type
- build_form_errors(form=None, errors=None, **kwargs)[source]¶
Return a dictionary of field errors for use in a response payload.
This will convert each error to a string, resulting in a dictionary mapping field names to lists of errors. This can be safely returned in any API payload.
New in version 1.0.9.
- Parameters
form (django.forms.Form, optional) – The form containing errors. This may be
None
if handling aValidationError
from field parsing.errors (django.core.exceptions.ValidationError, optional) – An explicit validation error to use for the payload. This will be used if field parsing fails.
**kwargs (dict) – Additional keyword arguments passed by the caller. This contains anything passed as keyword arguments to
handle_form_request()
.
- Returns
The dictionary of errors. Each key is a field name and each value is a list of error strings.
- Return type
- build_form_success_response(form, instance, is_created, **kwargs)[source]¶
Return a success response for a saved instance.
New in version 1.0.9.
- Parameters
form (django.forms.Form) – The form that saved the instance.
instance (django.db.models.Model) – The saved instance.
is_created (bool) – Whether the instance was created.
**kwargs (dict) – Additional keyword arguments passed by the caller. This contains anything passed as keyword arguments to
handle_form_request()
.
- Returns
The success response to return from the API handler.
- Return type
- build_form_error_response(form=None, errors=None, instance=None, **kwargs)[source]¶
Return an error response containing errors for form fields.
New in version 1.0.9.
- Parameters
form (django.forms.Form, optional) – The form containing errors. This may be
None
if handling aValidationError
from field parsing.errors (django.core.exceptions.ValidationError, optional) – An explicit validation error to use for the payload. This will be used if field parsing fails.
instance (django.db.models.Model, optional) – The existing instance, if any.
**kwargs (dict) – Additional keyword arguments passed by the caller. This contains anything passed as
response_kwargs
tohandle_form_request()
.
- Returns
The error response to return from the API handler.
- Return type