Ticket #1703: forms.txt.2.diff

File forms.txt.2.diff, 8.6 KB (added by Malcolm Tredinnick <malcolm@…>, 13 years ago)

Updated patch to work after Adrian's changes in [2765]

  • docs/forms.txt

    5454    >>> from mysite.myapp.models import Place
    5555    >>> Place.AddManipulator
    56     <class Place.ManipulatorAdd at 0x4c1540>
     56    <class 'django.models.manipulators.AddManipulator'>
    5757    >>> Place.ChangeManipulator
    58     <class Place.ManipulatorChange at 0x4c1630>
     58    <class 'django.models.manipulators.ChangeManipulator'>
    6060Using the ``AddManipulator``
    6666    from django.shortcuts import render_to_response
    6767    from django.http import Http404, HttpResponse, HttpResponseRedirect
     68    from django import forms
    6869    from mysite.myapp.models import Place
    69     from django import forms
    7171    def naive_create_place(request):
    7272        """A naive approach to creating places; don't actually use this!"""
    162162        if errors:
    163163            return render_to_response('places/errors.html', {'errors': errors})
    164164        else:
    165             manipulator.do_html2python(request.POST)
    166             new_place = manipulator.save(request.POST)
     165            manipulator.do_html2python(new_data)
     166            new_place = manipulator.save(new_data)
    167167            return HttpResponse("Place created: %s" % new_place)
    169169In this new version, errors will be found -- ``manipulator.get_validation_errors``
    198198both be available on the same page, so errors with fields can be presented in
    201 .. admonition:: Philosophy::
     201.. admonition:: Philosophy:
    203203    Finally, for the HTTP purists in the audience (and the authorship), this
    204204    nicely matches the "true" meanings of HTTP GET and HTTP POST: GET fetches
    408408One useful feature of manipulators is the automatic validation. Validation is
    409409done using a simple validation API: A validator is a callable that raises a
    410410``ValidationError`` if there's something wrong with the data.
    411 ``django.core.validators`` defines a host of validator functions, but defining
    412 your own couldn't be easier::
     411``django.core.validators`` defines a host of validator functions (see below),
     412but defining your own couldn't be easier::
    414414    from django.core import validators
    415415    from django import forms
    432432The arguments to a validator function take a little explanation.  ``field_data``
    433433is the value of the field in question, and ``all_data`` is a dictionary of all
    434 the data being validated.  Note that at the point validators are called all
    435 data will still be strings (as ``do_html2python`` hasn't been called yet).
     434the data being validated.
     436.. admonition:: Note::
     438    At the point validators are called all data will still be
     439    strings (as ``do_html2python`` hasn't been called yet).
    437441Also, because consistency in user interfaces is important, we strongly urge you
    438442to put punctuation at the end of your validation messages.
     444Ready-made Validators
     447Writing your own validator is not difficult, but there are some situations
     448that come up over and over again. Django comes with a number of validators
     449that can be used directly in your code. All of these functions and classes
     450reside in ``django/core/validators.py``.
     452The following validators should all be self-explanatory. Each one provides a
     453check for the given property:
     455    * isAlphaNumeric
     456    * isAlphaNumericURL
     457    * isSlug
     458    * isLowerCase
     459    * isUpperCase
     460    * isCommaSeparatedIntegerList
     461    * isCommaSeparatedEmailList
     462    * isValidIPAddress4
     463    * isNotEmpty
     464    * isOnlyDigits
     465    * isNotOnlyDigits
     466    * isInteger
     467    * isOnlyLetters
     468    * isValidANSIDate
     469    * isValidANSITime
     470    * isValidEmail
     471    * isValidImage
     472    * isValidImageURL
     473    * isValidPhone
     474    * isValidQuicktimeVideoURL
     475    * isValidURL
     476    * isValidHTML
     477    * isWellFormedXml
     478    * isWellFormedXmlFragment
     479    * isExistingURL
     480    * isValidUSState
     481    * hasNoProfanities
     483There are also a group of validators that are slightly more flexible. For
     484these validators, you create a validator instance, passing in the parameters
     485described below. The returned object is a callable that can be used as a
     488For example::
     490    from django.core import validators
     491    from django import forms
     493    power_validator = validators.IsAPowerOf(2)
     495    class InstallationManipulator(forms.Manipulator)
     496        def __init__(self):
     497            self.fields = (
     498                ...
     499                forms.IntegerField(field_name = "size",i
     500                        validator_list=[power_validator])
     501            )
     503Here, ``validators.IsAPowerOf(...)`` returned something that could be used as
     504a validator (in this case, a check that a number was a power of 2).
     506Each of the standard validators that take parameters have an optional final
     507argument (``error_message``) that is the message returned when validation
     508fails. If no message is passed in, a default message is used.
     511    Takes a field name and the current field is valid if and only if its value
     512    matches the contents of the other field.
     515    Takes three parameters: ``other_field``, ``other_value`` and
     516    ``validator_list``, in that order. If ``other_field`` has a value of
     517    ``other_vaue``, then the validators in ``validator_list`` are all run
     518    against the current field.
     521    Takes the name of the other field and this field is only required if the
     522    other field has no value.
     525    Similar to ``RequiredIfOtherFieldNotGiven``, except that it takes a list
     526    of field names and if any one of the supplied fields does not have a value
     527    provided, the field being validated is required.
     529``RequiredIfOtherFieldEquals`` and ``RequiredIfOtherFieldDoesNotEqual``
     530    Each of these validator classes takes a field name and a value (in that
     531    order). If the given field does (or does not have, in the latter case) the
     532    given value, then the current field being validated is required.
     534    Note that because validators are called before any ``do_html2python()``
     535    functions, the value being compared against is a string. So
     536    ``RequiredIfOtherFieldEquals('choice', '1')`` is correct, whilst
     537    ``RequiredIfOtherFieldEquals('choice', 1)`` will never result in the
     538    equality test succeeding.
     541    Takes a field name and validates that the current field being validated
     542    has a value that is less than (or equal to) the other field's value.
     543    Again, comparisons are done using strings, so be cautious about using
     544    this function to compare data that should be treated as another type. The
     545    string "123" is less than the string "2", for example. If you don't want
     546    string comparison here, you will need to write your own validator.
     549    Takes an integer argument and when called as a validator, checks that the
     550    field being validated is a power of the integer.
     553    Takes a maximum number of digits and number of decimal places (in that
     554    order) and validates whether the field is a float with less than the
     555    maximum number of digits and decimal place.
     558    Takes a regular expression (a string) as a parameter and validates the
     559    field value against it.
     562    Takes a list of validators as a parameter. At validation time, if the
     563    field successfully validates against any one of the validators, it passes
     564    validation. The validators are tested in the order specified in the
     565    original list.
     568    Used to validate URL fields. Takes a list of MIME types (such as
     569    ``text/plain``) at creation time. At validation time, it verifies that the
     570    field is indeed a URL and then tries to retrieve the content at the URL.
     571    Validation succeeds if the content could be retrieved and it has a content
     572    type from the list used to create the validator.
     575    Used to validate an XML document against a Relax NG compact schema. Takes
     576    a file path to the location of the schema and an optional root element
     577    (which is wrapped around the XML fragment before validation, if supplied).
     578    At validation time, the XML fragment is validated against the schema using
     579    the executable specified in the ``JING_PATH`` setting (see the settings_
     580    document for more details).
    440582.. _`generic views`: http://www.djangoproject.com/documentation/generic_views/
     583.. _`models API`: http://www.djangoproject.com/documentation/model_api/
     584.. _settings: http://www.djangoproject.com/documentation/settings/
Back to Top