diff options
Diffstat (limited to 'docs/ref/forms/fields.txt')
| -rw-r--r-- | docs/ref/forms/fields.txt | 102 |
1 files changed, 61 insertions, 41 deletions
diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 727f494da2..317a955a15 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -26,9 +26,9 @@ value: >>> from django import forms >>> f = forms.EmailField() - >>> f.clean('foo@example.com') + >>> f.clean("foo@example.com") 'foo@example.com' - >>> f.clean('invalid email address') + >>> f.clean("invalid email address") Traceback (most recent call last): ... ValidationError: ['Enter a valid email address.'] @@ -55,9 +55,9 @@ an empty value -- either ``None`` or the empty string (``""``) -- then >>> from django import forms >>> f = forms.CharField() - >>> f.clean('foo') + >>> f.clean("foo") 'foo' - >>> f.clean('') + >>> f.clean("") Traceback (most recent call last): ... ValidationError: ['This field is required.'] @@ -65,7 +65,7 @@ an empty value -- either ``None`` or the empty string (``""``) -- then Traceback (most recent call last): ... ValidationError: ['This field is required.'] - >>> f.clean(' ') + >>> f.clean(" ") ' ' >>> f.clean(0) '0' @@ -80,9 +80,9 @@ To specify that a field is *not* required, pass ``required=False`` to the .. code-block:: pycon >>> f = forms.CharField(required=False) - >>> f.clean('foo') + >>> f.clean("foo") 'foo' - >>> f.clean('') + >>> f.clean("") '' >>> f.clean(None) '' @@ -124,9 +124,10 @@ We've specified ``auto_id=False`` to simplify the output: >>> from django import forms >>> class CommentForm(forms.Form): - ... name = forms.CharField(label='Your name') - ... url = forms.URLField(label='Your website', required=False) + ... name = forms.CharField(label="Your name") + ... url = forms.URLField(label="Your website", required=False) ... comment = forms.CharField() + ... >>> f = CommentForm(auto_id=False) >>> print(f) <div>Your name:<input type="text" name="name" required></div> @@ -146,8 +147,9 @@ The ``label_suffix`` argument lets you override the form's >>> class ContactForm(forms.Form): ... age = forms.IntegerField() ... nationality = forms.CharField() - ... captcha_answer = forms.IntegerField(label='2 + 2', label_suffix=' =') - >>> f = ContactForm(label_suffix='?') + ... captcha_answer = forms.IntegerField(label="2 + 2", label_suffix=" =") + ... + >>> f = ContactForm(label_suffix="?") >>> print(f) <div><label for="id_age">Age?</label><input type="number" name="age" required id="id_age"></div> <div><label for="id_nationality">Nationality?</label><input type="text" name="nationality" required id="id_nationality"></div> @@ -170,9 +172,10 @@ field is initialized to a particular value. For example: >>> from django import forms >>> class CommentForm(forms.Form): - ... name = forms.CharField(initial='Your name') - ... url = forms.URLField(initial='http://') + ... name = forms.CharField(initial="Your name") + ... url = forms.URLField(initial="http://") ... comment = forms.CharField() + ... >>> f = CommentForm(auto_id=False) >>> print(f) <div>Name:<input type="text" name="name" value="Your name" required></div> @@ -189,7 +192,8 @@ and the HTML output will include any validation errors: ... name = forms.CharField() ... url = forms.URLField() ... comment = forms.CharField() - >>> default_data = {'name': 'Your name', 'url': 'http://'} + ... + >>> default_data = {"name": "Your name", "url": "http://"} >>> f = CommentForm(default_data, auto_id=False) >>> print(f) <div>Name:<input type="text" name="name" value="Your name" required></div> @@ -206,10 +210,11 @@ validation if a particular field's value is not given. ``initial`` values are .. code-block:: pycon >>> class CommentForm(forms.Form): - ... name = forms.CharField(initial='Your name') - ... url = forms.URLField(initial='http://') + ... name = forms.CharField(initial="Your name") + ... url = forms.URLField(initial="http://") ... comment = forms.CharField() - >>> data = {'name': '', 'url': '', 'comment': 'Foo'} + ... + >>> data = {"name": "", "url": "", "comment": "Foo"} >>> f = CommentForm(data) >>> f.is_valid() False @@ -224,6 +229,7 @@ Instead of a constant, you can also pass any callable: >>> import datetime >>> class DateForm(forms.Form): ... day = forms.DateField(initial=datetime.date.today) + ... >>> print(DateForm()) <div><label for="id_day">Day:</label><input type="text" name="day" value="2023-02-11" required id="id_day"></div> @@ -257,10 +263,11 @@ fields. We've specified ``auto_id=False`` to simplify the output: >>> from django import forms >>> class HelpTextContactForm(forms.Form): - ... subject = forms.CharField(max_length=100, help_text='100 characters max.') + ... subject = forms.CharField(max_length=100, help_text="100 characters max.") ... message = forms.CharField() - ... sender = forms.EmailField(help_text='A valid email address, please.') + ... sender = forms.EmailField(help_text="A valid email address, please.") ... cc_myself = forms.BooleanField(required=False) + ... >>> f = HelpTextContactForm(auto_id=False) >>> print(f) <div>Subject:<div class="helptext">100 characters max.</div><input type="text" name="subject" maxlength="100" required></div> @@ -281,7 +288,7 @@ want to override. For example, here is the default error message: >>> from django import forms >>> generic = forms.CharField() - >>> generic.clean('') + >>> generic.clean("") Traceback (most recent call last): ... ValidationError: ['This field is required.'] @@ -290,8 +297,8 @@ And here is a custom error message: .. code-block:: pycon - >>> name = forms.CharField(error_messages={'required': 'Please enter your name'}) - >>> name.clean('') + >>> name = forms.CharField(error_messages={"required": "Please enter your name"}) + >>> name.clean("") Traceback (most recent call last): ... ValidationError: ['Please enter your name'] @@ -746,12 +753,13 @@ For each field, we describe the default widget used if you don't specify >>> from django.core.files.uploadedfile import SimpleUploadedFile >>> class ImageForm(forms.Form): ... img = forms.ImageField() - >>> file_data = {'img': SimpleUploadedFile('test.png', b"file data")} + ... + >>> file_data = {"img": SimpleUploadedFile("test.png", b"file data")} >>> form = ImageForm({}, file_data) # Pillow closes the underlying file descriptor. >>> form.is_valid() True - >>> image_field = form.cleaned_data['img'] + >>> image_field = form.cleaned_data["img"] >>> image_field.image <PIL.PngImagePlugin.PngImageFile image mode=RGBA size=191x287 at 0x7F5985045C18> >>> image_field.image.width @@ -893,9 +901,9 @@ For each field, we describe the default widget used if you don't specify NullBooleanField( widget=Select( choices=[ - ('', 'Unknown'), - (True, 'Yes'), - (False, 'No'), + ("", "Unknown"), + (True, "Yes"), + (False, "No"), ] ) ) @@ -1141,32 +1149,35 @@ Slightly complex built-in ``Field`` classes from django.core.validators import RegexValidator + class PhoneField(MultiValueField): def __init__(self, **kwargs): # Define one message for all fields. error_messages = { - 'incomplete': 'Enter a country calling code and a phone number.', + "incomplete": "Enter a country calling code and a phone number.", } # Or define a different message for each field. fields = ( CharField( - error_messages={'incomplete': 'Enter a country calling code.'}, + error_messages={"incomplete": "Enter a country calling code."}, validators=[ - RegexValidator(r'^[0-9]+$', 'Enter a valid country calling code.'), + RegexValidator(r"^[0-9]+$", "Enter a valid country calling code."), ], ), CharField( - error_messages={'incomplete': 'Enter a phone number.'}, - validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid phone number.')], + error_messages={"incomplete": "Enter a phone number."}, + validators=[RegexValidator(r"^[0-9]+$", "Enter a valid phone number.")], ), CharField( - validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid extension.')], + validators=[RegexValidator(r"^[0-9]+$", "Enter a valid extension.")], required=False, ), ) super().__init__( - error_messages=error_messages, fields=fields, - require_all_fields=False, **kwargs + error_messages=error_messages, + fields=fields, + require_all_fields=False, + **kwargs ) .. attribute:: MultiValueField.widget @@ -1238,7 +1249,7 @@ method:: def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) - self.fields['foo_select'].queryset = ... + self.fields["foo_select"].queryset = ... Both ``ModelChoiceField`` and ``ModelMultipleChoiceField`` have an ``iterator`` attribute which specifies the class used to iterate over the queryset when @@ -1351,6 +1362,7 @@ generating choices. See :ref:`iterating-relationship-choices` for details. from django.forms import ModelChoiceField + class MyModelChoiceField(ModelChoiceField): def label_from_instance(self, obj): return "My Object #%i" % obj.id @@ -1416,6 +1428,7 @@ For example, consider the following models:: from django.db import models + class Topping(models.Model): name = models.CharField(max_length=100) price = models.DecimalField(decimal_places=2, max_digits=6) @@ -1423,6 +1436,7 @@ For example, consider the following models:: def __str__(self): return self.name + class Pizza(models.Model): topping = models.ForeignKey(Topping, on_delete=models.CASCADE) @@ -1432,18 +1446,24 @@ the value of ``Topping.price`` as the HTML attribute ``data-price`` for each from django import forms + class ToppingSelect(forms.Select): - def create_option(self, name, value, label, selected, index, subindex=None, attrs=None): - option = super().create_option(name, value, label, selected, index, subindex, attrs) + def create_option( + self, name, value, label, selected, index, subindex=None, attrs=None + ): + option = super().create_option( + name, value, label, selected, index, subindex, attrs + ) if value: - option['attrs']['data-price'] = value.instance.price + option["attrs"]["data-price"] = value.instance.price return option + class PizzaForm(forms.ModelForm): class Meta: model = Pizza - fields = ['topping'] - widgets = {'topping': ToppingSelect} + fields = ["topping"] + widgets = {"topping": ToppingSelect} This will render the ``Pizza.topping`` select as: |