From 6789ded0a6ab797f0dcdfa6ad5d1cfa46e23abcd Mon Sep 17 00:00:00 2001 From: sage Date: Sun, 9 Jun 2019 07:56:37 +0700 Subject: Fixed #12990, Refs #27694 -- Added JSONField model field. Thanks to Adam Johnson, Carlton Gibson, Mariusz Felisiak, and Raphael Michel for mentoring this Google Summer of Code 2019 project and everyone else who helped with the patch. Special thanks to Mads Jensen, Nick Pope, and Simon Charette for extensive reviews. Co-authored-by: Mariusz Felisiak --- docs/ref/forms/fields.txt | 54 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) (limited to 'docs/ref/forms') diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 3d228e88ad..58db957512 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -776,6 +776,60 @@ For each field, we describe the default widget used if you don't specify These control the range of values permitted in the field. +``JSONField`` +------------- + +.. class:: JSONField(encoder=None, decoder=None, **kwargs) + + .. versionadded:: 3.1 + + A field which accepts JSON encoded data for a + :class:`~django.db.models.JSONField`. + + * Default widget: :class:`Textarea` + * Empty value: ``''`` (an empty string) + * Normalizes to: A Python representation of the JSON value (usually as a + ``dict``, ``list``, or ``None``), depending on :attr:`JSONField.decoder`. + * Validates that the given value is a valid JSON. + * Error message keys: ``required``, ``invalid`` + + Takes two optional arguments: + + .. attribute:: encoder + + A :py:class:`json.JSONEncoder` subclass to serialize data types not + supported by the standard JSON serializer (e.g. ``datetime.datetime`` + or :class:`~python:uuid.UUID`). For example, you can use the + :class:`~django.core.serializers.json.DjangoJSONEncoder` class. + + Defaults to ``json.JSONEncoder``. + + .. attribute:: decoder + + A :py:class:`json.JSONDecoder` subclass to deserialize the input. Your + deserialization may need to account for the fact that you can't be + certain of the input type. For example, you run the risk of returning a + ``datetime`` that was actually a string that just happened to be in the + same format chosen for ``datetime``\s. + + The ``decoder`` can be used to validate the input. If + :py:class:`json.JSONDecodeError` is raised during the deserialization, + a ``ValidationError`` will be raised. + + Defaults to ``json.JSONDecoder``. + + .. note:: + + If you use a :class:`ModelForm `, the + ``encoder`` and ``decoder`` from :class:`~django.db.models.JSONField` + will be used. + + .. admonition:: User friendly forms + + ``JSONField`` is not particularly user friendly in most cases. However, + it is a useful way to format data from a client-side widget for + submission to the server. + ``GenericIPAddressField`` ------------------------- -- cgit v1.3