djblets.webapi.resources.mixins.forms¶
Mixins for integrating a web API resource with a form.
- class UpdateFormMixin¶
Bases:
object
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¶
The form class for updating models.
This should be a subclass of
django.forms.ModelForm
.
- property add_form_class¶
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)¶
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 tocreate_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’sModelForm.save()
method.**kwargs (
dict
) – Keyword arguments to pass tobuild_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)¶
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 notNone
, 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)¶
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 tohandle_form_request()
.
- Returns:
The saved model instance.
- Return type:
- build_form_errors(form=None, errors=None, **kwargs)¶
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 beNone
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 tohandle_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)¶
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 tohandle_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)¶
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 beNone
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 asresponse_kwargs
tohandle_form_request()
.
- Returns:
The error response to return from the API handler.
- Return type: