mirror of
https://github.com/django/django.git
synced 2024-12-24 18:16:19 +00:00
4a954cfd11
This patch does not remove all occurrences of the words in question. Rather, I went through all of the occurrences of the words listed below, and judged if they a) suggested the reader had some kind of knowledge/experience, and b) if they added anything of value (including tone of voice, etc). I left most of the words alone. I looked at the following words: - simply/simple - easy/easier/easiest - obvious - just - merely - straightforward - ridiculous Thanks to Carlton Gibson for guidance on how to approach this issue, and to Tim Bell for providing the idea. But the enormous lion's share of thanks go to Adam Johnson for his patient and helpful review.
259 lines
8.4 KiB
Plaintext
259 lines
8.4 KiB
Plaintext
===========================================
|
|
PostgreSQL specific form fields and widgets
|
|
===========================================
|
|
|
|
All of these fields and widgets are available from the
|
|
``django.contrib.postgres.forms`` module.
|
|
|
|
.. currentmodule:: django.contrib.postgres.forms
|
|
|
|
Fields
|
|
======
|
|
|
|
``SimpleArrayField``
|
|
--------------------
|
|
|
|
.. class:: SimpleArrayField(base_field, delimiter=',', max_length=None, min_length=None)
|
|
|
|
A field which maps to an array. It is represented by an HTML ``<input>``.
|
|
|
|
.. attribute:: base_field
|
|
|
|
This is a required argument.
|
|
|
|
It specifies the underlying form field for the array. This is not used
|
|
to render any HTML, but it is used to process the submitted data and
|
|
validate it. For example::
|
|
|
|
>>> from django import forms
|
|
>>> from django.contrib.postgres.forms import SimpleArrayField
|
|
|
|
>>> class NumberListForm(forms.Form):
|
|
... numbers = SimpleArrayField(forms.IntegerField())
|
|
|
|
>>> form = NumberListForm({'numbers': '1,2,3'})
|
|
>>> form.is_valid()
|
|
True
|
|
>>> form.cleaned_data
|
|
{'numbers': [1, 2, 3]}
|
|
|
|
>>> form = NumberListForm({'numbers': '1,2,a'})
|
|
>>> form.is_valid()
|
|
False
|
|
|
|
.. attribute:: delimiter
|
|
|
|
This is an optional argument which defaults to a comma: ``,``. This
|
|
value is used to split the submitted data. It allows you to chain
|
|
``SimpleArrayField`` for multidimensional data::
|
|
|
|
>>> from django import forms
|
|
>>> from django.contrib.postgres.forms import SimpleArrayField
|
|
|
|
>>> class GridForm(forms.Form):
|
|
... places = SimpleArrayField(SimpleArrayField(IntegerField()), delimiter='|')
|
|
|
|
>>> form = GridForm({'places': '1,2|2,1|4,3'})
|
|
>>> form.is_valid()
|
|
True
|
|
>>> form.cleaned_data
|
|
{'places': [[1, 2], [2, 1], [4, 3]]}
|
|
|
|
.. note::
|
|
|
|
The field does not support escaping of the delimiter, so be careful
|
|
in cases where the delimiter is a valid character in the underlying
|
|
field. The delimiter does not need to be only one character.
|
|
|
|
.. attribute:: max_length
|
|
|
|
This is an optional argument which validates that the array does not
|
|
exceed the stated length.
|
|
|
|
.. attribute:: min_length
|
|
|
|
This is an optional argument which validates that the array reaches at
|
|
least the stated length.
|
|
|
|
.. admonition:: User friendly forms
|
|
|
|
``SimpleArrayField`` 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.
|
|
|
|
``SplitArrayField``
|
|
-------------------
|
|
|
|
.. class:: SplitArrayField(base_field, size, remove_trailing_nulls=False)
|
|
|
|
This field handles arrays by reproducing the underlying field a fixed
|
|
number of times.
|
|
|
|
.. attribute:: base_field
|
|
|
|
This is a required argument. It specifies the form field to be
|
|
repeated.
|
|
|
|
.. attribute:: size
|
|
|
|
This is the fixed number of times the underlying field will be used.
|
|
|
|
.. attribute:: remove_trailing_nulls
|
|
|
|
By default, this is set to ``False``. When ``False``, each value from
|
|
the repeated fields is stored. When set to ``True``, any trailing
|
|
values which are blank will be stripped from the result. If the
|
|
underlying field has ``required=True``, but ``remove_trailing_nulls``
|
|
is ``True``, then null values are only allowed at the end, and will be
|
|
stripped.
|
|
|
|
Some examples::
|
|
|
|
SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=False)
|
|
|
|
['1', '2', '3'] # -> [1, 2, 3]
|
|
['1', '2', ''] # -> ValidationError - third entry required.
|
|
['1', '', '3'] # -> ValidationError - second entry required.
|
|
['', '2', ''] # -> ValidationError - first and third entries required.
|
|
|
|
SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=False)
|
|
|
|
['1', '2', '3'] # -> [1, 2, 3]
|
|
['1', '2', ''] # -> [1, 2, None]
|
|
['1', '', '3'] # -> [1, None, 3]
|
|
['', '2', ''] # -> [None, 2, None]
|
|
|
|
SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=True)
|
|
|
|
['1', '2', '3'] # -> [1, 2, 3]
|
|
['1', '2', ''] # -> [1, 2]
|
|
['1', '', '3'] # -> ValidationError - second entry required.
|
|
['', '2', ''] # -> ValidationError - first entry required.
|
|
|
|
SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=True)
|
|
|
|
['1', '2', '3'] # -> [1, 2, 3]
|
|
['1', '2', ''] # -> [1, 2]
|
|
['1', '', '3'] # -> [1, None, 3]
|
|
['', '2', ''] # -> [None, 2]
|
|
|
|
``HStoreField``
|
|
---------------
|
|
|
|
.. class:: HStoreField
|
|
|
|
A field which accepts JSON encoded data for an
|
|
:class:`~django.contrib.postgres.fields.HStoreField`. It casts all values
|
|
(except nulls) to strings. It is represented by an HTML ``<textarea>``.
|
|
|
|
.. admonition:: User friendly forms
|
|
|
|
``HStoreField`` 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.
|
|
|
|
.. note::
|
|
|
|
On occasions it may be useful to require or restrict the keys which are
|
|
valid for a given field. This can be done using the
|
|
:class:`~django.contrib.postgres.validators.KeysValidator`.
|
|
|
|
``JSONField``
|
|
-------------
|
|
|
|
.. class:: JSONField
|
|
|
|
A field which accepts JSON encoded data for a
|
|
:class:`~django.contrib.postgres.fields.JSONField`. It is represented by an
|
|
HTML ``<textarea>``.
|
|
|
|
.. 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.
|
|
|
|
Range Fields
|
|
------------
|
|
|
|
This group of fields all share similar functionality for accepting range data.
|
|
They are based on :class:`~django.forms.MultiValueField`. They treat one
|
|
omitted value as an unbounded range. They also validate that the lower bound is
|
|
not greater than the upper bound. All of these fields use
|
|
:class:`~django.contrib.postgres.forms.RangeWidget`.
|
|
|
|
``IntegerRangeField``
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. class:: IntegerRangeField
|
|
|
|
Based on :class:`~django.forms.IntegerField` and translates its input into
|
|
:class:`~psycopg2:psycopg2.extras.NumericRange`. Default for
|
|
:class:`~django.contrib.postgres.fields.IntegerRangeField` and
|
|
:class:`~django.contrib.postgres.fields.BigIntegerRangeField`.
|
|
|
|
``DecimalRangeField``
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. class:: DecimalRangeField
|
|
|
|
.. versionadded:: 2.2
|
|
|
|
Based on :class:`~django.forms.DecimalField` and translates its input into
|
|
:class:`~psycopg2:psycopg2.extras.NumericRange`. Default for
|
|
:class:`~django.contrib.postgres.fields.DecimalRangeField`.
|
|
|
|
``FloatRangeField``
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. class:: FloatRangeField
|
|
|
|
Based on :class:`~django.forms.FloatField` and translates its input into
|
|
:class:`~psycopg2:psycopg2.extras.NumericRange`. Default for
|
|
:class:`~django.contrib.postgres.fields.FloatRangeField`.
|
|
|
|
.. deprecated:: 2.2
|
|
|
|
Use :class:`DecimalRangeField` instead.
|
|
|
|
``DateTimeRangeField``
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. class:: DateTimeRangeField
|
|
|
|
Based on :class:`~django.forms.DateTimeField` and translates its input into
|
|
:class:`~psycopg2:psycopg2.extras.DateTimeTZRange`. Default for
|
|
:class:`~django.contrib.postgres.fields.DateTimeRangeField`.
|
|
|
|
``DateRangeField``
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
.. class:: DateRangeField
|
|
|
|
Based on :class:`~django.forms.DateField` and translates its input into
|
|
:class:`~psycopg2:psycopg2.extras.DateRange`. Default for
|
|
:class:`~django.contrib.postgres.fields.DateRangeField`.
|
|
|
|
Widgets
|
|
=======
|
|
|
|
``RangeWidget``
|
|
---------------
|
|
|
|
.. class:: RangeWidget(base_widget, attrs=None)
|
|
|
|
Widget used by all of the range fields.
|
|
Based on :class:`~django.forms.MultiWidget`.
|
|
|
|
:class:`~RangeWidget` has one required argument:
|
|
|
|
.. attribute:: base_widget
|
|
|
|
A :class:`~RangeWidget` comprises a 2-tuple of ``base_widget``.
|
|
|
|
.. method:: decompress(value)
|
|
|
|
Takes a single "compressed" value of a field, for example a
|
|
:class:`~django.contrib.postgres.fields.DateRangeField`,
|
|
and returns a tuple representing and lower and upper bound.
|