| 1 |
=========================================== |
| 2 |
PostgreSQL specific form fields and widgets |
| 3 |
=========================================== |
| 4 |
|
| 5 |
All of these fields and widgets are available from the |
| 6 |
``django.contrib.postgres.forms`` module. |
| 7 |
|
| 8 |
.. currentmodule:: django.contrib.postgres.forms |
| 9 |
|
| 10 |
Fields |
| 11 |
====== |
| 12 |
|
| 13 |
``SimpleArrayField`` |
| 14 |
-------------------- |
| 15 |
|
| 16 |
.. class:: SimpleArrayField(base_field, delimiter=',', max_length=None, min_length=None) |
| 17 |
|
| 18 |
A field which maps to an array. It is represented by an HTML ``<input>``. |
| 19 |
|
| 20 |
.. attribute:: base_field |
| 21 |
|
| 22 |
This is a required argument. |
| 23 |
|
| 24 |
It specifies the underlying form field for the array. This is not used |
| 25 |
to render any HTML, but it is used to process the submitted data and |
| 26 |
validate it. For example: |
| 27 |
|
| 28 |
.. code-block:: pycon |
| 29 |
|
| 30 |
>>> from django import forms |
| 31 |
>>> from django.contrib.postgres.forms import SimpleArrayField |
| 32 |
|
| 33 |
>>> class NumberListForm(forms.Form): |
| 34 |
... numbers = SimpleArrayField(forms.IntegerField()) |
| 35 |
... |
| 36 |
|
| 37 |
>>> form = NumberListForm({"numbers": "1,2,3"}) |
| 38 |
>>> form.is_valid() |
| 39 |
True |
| 40 |
>>> form.cleaned_data |
| 41 |
{'numbers': [1, 2, 3]} |
| 42 |
|
| 43 |
>>> form = NumberListForm({"numbers": "1,2,a"}) |
| 44 |
>>> form.is_valid() |
| 45 |
False |
| 46 |
|
| 47 |
.. attribute:: delimiter |
| 48 |
|
| 49 |
This is an optional argument which defaults to a comma: ``,``. This |
| 50 |
value is used to split the submitted data. It allows you to chain |
| 51 |
``SimpleArrayField`` for multidimensional data: |
| 52 |
|
| 53 |
.. code-block:: pycon |
| 54 |
|
| 55 |
>>> from django import forms |
| 56 |
>>> from django.contrib.postgres.forms import SimpleArrayField |
| 57 |
|
| 58 |
>>> class GridForm(forms.Form): |
| 59 |
... places = SimpleArrayField(SimpleArrayField(IntegerField()), delimiter="|") |
| 60 |
... |
| 61 |
|
| 62 |
>>> form = GridForm({"places": "1,2|2,1|4,3"}) |
| 63 |
>>> form.is_valid() |
| 64 |
True |
| 65 |
>>> form.cleaned_data |
| 66 |
{'places': [[1, 2], [2, 1], [4, 3]]} |
| 67 |
|
| 68 |
.. note:: |
| 69 |
|
| 70 |
The field does not support escaping of the delimiter, so be careful |
| 71 |
in cases where the delimiter is a valid character in the underlying |
| 72 |
field. The delimiter does not need to be only one character. |
| 73 |
|
| 74 |
.. attribute:: max_length |
| 75 |
|
| 76 |
This is an optional argument which validates that the array does not |
| 77 |
exceed the stated length. |
| 78 |
|
| 79 |
.. attribute:: min_length |
| 80 |
|
| 81 |
This is an optional argument which validates that the array reaches at |
| 82 |
least the stated length. |
| 83 |
|
| 84 |
.. admonition:: User friendly forms |
| 85 |
|
| 86 |
``SimpleArrayField`` is not particularly user friendly in most cases, |
| 87 |
however it is a useful way to format data from a client-side widget for |
| 88 |
submission to the server. |
| 89 |
|
| 90 |
``SplitArrayField`` |
| 91 |
------------------- |
| 92 |
|
| 93 |
.. class:: SplitArrayField(base_field, size, remove_trailing_nulls=False) |
| 94 |
|
| 95 |
This field handles arrays by reproducing the underlying field a fixed |
| 96 |
number of times. |
| 97 |
|
| 98 |
.. attribute:: base_field |
| 99 |
|
| 100 |
This is a required argument. It specifies the form field to be |
| 101 |
repeated. |
| 102 |
|
| 103 |
.. attribute:: size |
| 104 |
|
| 105 |
This is the fixed number of times the underlying field will be used. |
| 106 |
|
| 107 |
.. attribute:: remove_trailing_nulls |
| 108 |
|
| 109 |
By default, this is set to ``False``. When ``False``, each value from |
| 110 |
the repeated fields is stored. When set to ``True``, any trailing |
| 111 |
values which are blank will be stripped from the result. If the |
| 112 |
underlying field has ``required=True``, but ``remove_trailing_nulls`` |
| 113 |
is ``True``, then null values are only allowed at the end, and will be |
| 114 |
stripped. |
| 115 |
|
| 116 |
Some examples:: |
| 117 |
|
| 118 |
SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=False) |
| 119 |
|
| 120 |
["1", "2", "3"] # -> [1, 2, 3] |
| 121 |
["1", "2", ""] # -> ValidationError - third entry required. |
| 122 |
["1", "", "3"] # -> ValidationError - second entry required. |
| 123 |
["", "2", ""] # -> ValidationError - first and third entries required. |
| 124 |
|
| 125 |
SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=False) |
| 126 |
|
| 127 |
["1", "2", "3"] # -> [1, 2, 3] |
| 128 |
["1", "2", ""] # -> [1, 2, None] |
| 129 |
["1", "", "3"] # -> [1, None, 3] |
| 130 |
["", "2", ""] # -> [None, 2, None] |
| 131 |
|
| 132 |
SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=True) |
| 133 |
|
| 134 |
["1", "2", "3"] # -> [1, 2, 3] |
| 135 |
["1", "2", ""] # -> [1, 2] |
| 136 |
["1", "", "3"] # -> ValidationError - second entry required. |
| 137 |
["", "2", ""] # -> ValidationError - first entry required. |
| 138 |
|
| 139 |
SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=True) |
| 140 |
|
| 141 |
["1", "2", "3"] # -> [1, 2, 3] |
| 142 |
["1", "2", ""] # -> [1, 2] |
| 143 |
["1", "", "3"] # -> [1, None, 3] |
| 144 |
["", "2", ""] # -> [None, 2] |
| 145 |
|
| 146 |
``HStoreField`` |
| 147 |
--------------- |
| 148 |
|
| 149 |
.. class:: HStoreField |
| 150 |
|
| 151 |
A field which accepts JSON encoded data for an |
| 152 |
:class:`~django.contrib.postgres.fields.HStoreField`. It casts all values |
| 153 |
(except nulls) to strings. It is represented by an HTML ``<textarea>``. |
| 154 |
|
| 155 |
.. admonition:: User friendly forms |
| 156 |
|
| 157 |
``HStoreField`` is not particularly user friendly in most cases, |
| 158 |
however it is a useful way to format data from a client-side widget for |
| 159 |
submission to the server. |
| 160 |
|
| 161 |
.. note:: |
| 162 |
|
| 163 |
On occasions it may be useful to require or restrict the keys which are |
| 164 |
valid for a given field. This can be done using the |
| 165 |
:class:`~django.contrib.postgres.validators.KeysValidator`. |
| 166 |
|
| 167 |
Range Fields |
| 168 |
------------ |
| 169 |
|
| 170 |
This group of fields all share similar functionality for accepting range data. |
| 171 |
They are based on :class:`~django.forms.MultiValueField`. They treat one |
| 172 |
omitted value as an unbounded range. They also validate that the lower bound is |
| 173 |
not greater than the upper bound. All of these fields use |
| 174 |
:class:`~django.contrib.postgres.forms.RangeWidget`. |
| 175 |
|
| 176 |
``IntegerRangeField`` |
| 177 |
~~~~~~~~~~~~~~~~~~~~~ |
| 178 |
|
| 179 |
.. class:: IntegerRangeField |
| 180 |
|
| 181 |
Based on :class:`~django.forms.IntegerField` and translates its input into |
| 182 |
``django.db.backends.postgresql.psycopg_any.NumericRange``. Default for |
| 183 |
:class:`~django.contrib.postgres.fields.IntegerRangeField` and |
| 184 |
:class:`~django.contrib.postgres.fields.BigIntegerRangeField`. |
| 185 |
|
| 186 |
``DecimalRangeField`` |
| 187 |
~~~~~~~~~~~~~~~~~~~~~ |
| 188 |
|
| 189 |
.. class:: DecimalRangeField |
| 190 |
|
| 191 |
Based on :class:`~django.forms.DecimalField` and translates its input into |
| 192 |
``django.db.backends.postgresql.psycopg_any.NumericRange``. Default for |
| 193 |
:class:`~django.contrib.postgres.fields.DecimalRangeField`. |
| 194 |
|
| 195 |
``DateTimeRangeField`` |
| 196 |
~~~~~~~~~~~~~~~~~~~~~~ |
| 197 |
|
| 198 |
.. class:: DateTimeRangeField |
| 199 |
|
| 200 |
Based on :class:`~django.forms.DateTimeField` and translates its input into |
| 201 |
``django.db.backends.postgresql.psycopg_any.DateTimeTZRange``. Default for |
| 202 |
:class:`~django.contrib.postgres.fields.DateTimeRangeField`. |
| 203 |
|
| 204 |
``DateRangeField`` |
| 205 |
~~~~~~~~~~~~~~~~~~ |
| 206 |
|
| 207 |
.. class:: DateRangeField |
| 208 |
|
| 209 |
Based on :class:`~django.forms.DateField` and translates its input into |
| 210 |
``django.db.backends.postgresql.psycopg_any.DateRange``. Default for |
| 211 |
:class:`~django.contrib.postgres.fields.DateRangeField`. |
| 212 |
|
| 213 |
Widgets |
| 214 |
======= |
| 215 |
|
| 216 |
``RangeWidget`` |
| 217 |
--------------- |
| 218 |
|
| 219 |
.. class:: RangeWidget(base_widget, attrs=None) |
| 220 |
|
| 221 |
Widget used by all of the range fields. |
| 222 |
Based on :class:`~django.forms.MultiWidget`. |
| 223 |
|
| 224 |
:class:`~RangeWidget` has one required argument: |
| 225 |
|
| 226 |
.. attribute:: base_widget |
| 227 |
|
| 228 |
A :class:`~RangeWidget` comprises a 2-tuple of ``base_widget``. |
| 229 |
|
| 230 |
.. method:: decompress(value) |
| 231 |
|
| 232 |
Takes a single "compressed" value of a field, for example a |
| 233 |
:class:`~django.contrib.postgres.fields.DateRangeField`, |
| 234 |
and returns a tuple representing a lower and upper bound. |