djblets.webapi.resources.mixins.forms¶
Mixins for integrating a web API resource with a form.
-
class
UpdateFormMixin
[source]¶ 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[source]¶ The form class for updating models.
This should be a subclass of
django.forms.ModelForm
.
-
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 anyparse_*
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: - form (django.forms.Form, optional) – The form containing errors. This may be
-
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: - form (django.forms.Form, optional) – The form containing errors. This may be
-