Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Added formfields/manipulators docs; added a few notes to the FAQ

git-svn-id: http://code.djangoproject.com/svn/django/trunk@303 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 8bd30b01e401e7ed8ef87bf42bec2614e8d96570 1 parent 768c17e
Jacob Kaplan-Moss authored July 24, 2005
34  docs/faq.txt
@@ -101,10 +101,22 @@ any capital-M Methodologies; we do what "feels" right. If you squint the right
101 101
 way, you can call Django's ORM the "Model", the view functions the "View", and
102 102
 the dynamically-generated API the "Controller" -- but not really.
103 103
 
  104
+In fact, you might say that Django is a "MTV" framework -- that is, Model,
  105
+Template, and View make much more sense to us.
  106
+
104 107
 So, although we've been strongly influenced by MVC -- especially in the
105 108
 separation-of-data-from-logic department -- we've also strayed from the path
106 109
 where it makes sense.
107 110
 
  111
+<Framework X> does <feature Y> -- why doesn't Django?
  112
+-----------------------------------------------------
  113
+
  114
+We're well aware that there are other awesome web frameworks out there, and
  115
+we're not adverse to borrowing ideas where appropriate.  However, Django was
  116
+developed precisely because we were unhappy with the status quo, so please be
  117
+aware that "because <Framework X>" does it is not going to be sufficient reason
  118
+to add a given feature to Django.
  119
+
108 120
 Do you have any of those nifty "screencast" things?
109 121
 ---------------------------------------------------
110 122
 
@@ -224,6 +236,28 @@ but we recognize that choosing a template language runs close to religion.
224 236
 There's nothing about Django that requires using the template language, so
225 237
 if you're attached to ZPT, Cheetah, or whatever, feel free to use those.
226 238
 
  239
+How do I use image and file fields?
  240
+-----------------------------------
  241
+
  242
+Using a ``FileField`` or an ``ImageField`` in a model takes a few steps:
  243
+
  244
+    #. In your settings file, define ``MEDIA_ROOT`` as the full path to
  245
+       a directory where you'd like Django to store uploaded files (for
  246
+       performance these files are not stored in the database).  Define
  247
+       ``MEDIA_URL`` as the base public URL of that directory.  Make
  248
+       sure that this directory is writable by the web user.
  249
+       
  250
+    #. Add the ``FileField`` or ``ImageField`` to your model, making sure
  251
+       to define the ``upload_to`` option to tell Django what subdirectory
  252
+       of ``MEDIA_ROOT`` to upload files to.
  253
+       
  254
+    #. All that will be stored in your database is a path to the file 
  255
+       (relative to ``MEDIA_ROOT``).  You'll must likely want to use
  256
+       the convenience ``get_<fieldname>_url`` function provided by 
  257
+       Django (that is, if your ``ImageField`` is called ``mug_shot``,
  258
+       you can get the absolute URL to your image in a template with
  259
+       ``{{ object.get_mug_shot_url }}``.
  260
+
227 261
 The database API
228 262
 ================
229 263
 
456  docs/forms.txt
... ...
@@ -0,0 +1,456 @@
  1
+===============================
  2
+Forms, fields, and manipulators
  3
+===============================
  4
+
  5
+Once you've got a chance to play with Django's admin interface, you'll probably
  6
+wonder if the fantastic form validation framework it uses is available to user
  7
+code.  It is, and this document explains how the framework works.
  8
+
  9
+    .. admonition:: A note to the lazy
  10
+    
  11
+        If all you want to do is present forms for a user to create and/or
  12
+        update a given object, don't read any further but instead click thyself
  13
+        over to the `generic views`_ documentation. The following exercises are
  14
+        for those interested in how Django's form framework works and those
  15
+        needing to do more than simple create/update.
  16
+
  17
+We'll take a top-down approach to examining Django's form validation framework
  18
+since much of the time you won't need to use the lower-level APIs.  Throughout
  19
+this document, we'll be working with the following model, a "place" object::
  20
+    
  21
+    PLACE_TYPES = (
  22
+        (1, 'Bar'),
  23
+        (2, 'Restaurant'),
  24
+        (3, 'Movie Theater'),
  25
+        (4, 'Secret Hideout'),
  26
+    )
  27
+    
  28
+    class Place(meta.Model):
  29
+        fields = (
  30
+            meta.CharField('name', 'name', maxlength=100),
  31
+            meta.CharField('address', 'address', maxlength=100, blank=True),
  32
+            meta.CharField('city', 'city', maxlength=50, blank=True),
  33
+            meta.USStateField('state', 'state'),
  34
+            meta.CharField('zip_code', 'zip code', maxlength=5, blank=True),
  35
+            meta.IntegerField('place_type', 'place type', choices=PLACE_TYPES)
  36
+        )
  37
+        
  38
+        def __repr__(self):
  39
+            return self.name
  40
+
  41
+Defining the above class is enough to create an admin interface to a ``place``,
  42
+but what if you want to allow public users to submit places?
  43
+
  44
+Manipulators
  45
+============
  46
+
  47
+The highest-level interface for object creation and modification is the
  48
+**Manipulator** framework. A manipulator is a utility class tied to a given
  49
+model that "knows" how to create or modify instances of that model and how to
  50
+validate data for the object.  Manipulators come in two flavors:
  51
+``AddManipulators`` and ``ChangeManipulators``.  Functionally they are quite
  52
+similar, but the former knows how to create new instances of the model, while
  53
+the later modifies existing instances.  Both types of classes are automatically
  54
+created when you define a new class::
  55
+
  56
+    >>> from django.models.places import places
  57
+    >>> places.AddManipulator
  58
+    <class django.models.places.PlaceManipulatorAdd at 0x4c1540>
  59
+    >>> places.ChangeManipulator
  60
+    <class django.models.places.PlaceManipulatorChange at 0x4c1630>
  61
+    
  62
+Using the ``AddManipulator``
  63
+----------------------------
  64
+    
  65
+We'll start with the ``AddManipulator``.  Here's a very simple view that takes
  66
+POSTed data from the browser and creates a new ``Place`` object::
  67
+
  68
+    from django.core import template_loader
  69
+    from django.core.exceptions import Http404
  70
+    from django.core.extensions import DjangoContext as Context
  71
+    from django.utils.httpwrappers import HttpResponse, HttpResponseRedirect
  72
+    from django.models.places import places
  73
+    from django.core import formfields
  74
+
  75
+    def naive_create_place(request):
  76
+        """A naive approach to creating places; don't actually use this!"""
  77
+        # Create the AddManipulator
  78
+        manipulator = places.AddManipulator()
  79
+        
  80
+        # Make a copy of the POSTed data so that do_html2python can
  81
+        # modify it in place (request.POST is immutable)
  82
+        new_data = request.POST.copy()
  83
+        
  84
+        # Convert the request data (which will all be strings) into the
  85
+        # appropriate Python types for those fields
  86
+        manipulator.do_html2python(new_data)
  87
+        
  88
+        # Save the new object
  89
+        new_place = manipulator.save(new_data)
  90
+        
  91
+        # It worked!
  92
+        return HttpResponse("Place created: %s" % new_place)
  93
+
  94
+The ``naive_create_place`` example works (somewhat), but as you probably can
  95
+tell, there's all sorts of problems (some more subtle than others) with this view:
  96
+
  97
+    * No validation of any sort is performed; if, for example, the ``name`` field
  98
+      isn't given in ``request.POST``, the save step will cause a database error
  99
+      because that field is required.  Ugly.
  100
+
  101
+    * Even if you *do* perform validation, there's still no way to give that information
  102
+      to the user is any sort of useful way.
  103
+      
  104
+    * You'll have to separate create a form (and view) that submits to this page, which is
  105
+      a pain and is redundant.
  106
+      
  107
+Let's dodge these problems momentarily to take a look at how you could create a
  108
+view with a form that submits to this flawed creation view::
  109
+
  110
+    def naive_create_place_form(request):
  111
+        """Simplistic place form view; don't actually use anything like this!"""
  112
+        # Create a FormWrapper object which the template can use; more
  113
+        # on what the second two arguments to FormWrapper do later.
  114
+        form = formfields.FormWrapper(places.AddManipulator(), {}, {})
  115
+        
  116
+        # Create a template, context, and response
  117
+        t = template_loader.get_template('places/naive_create_form')
  118
+        c = Context(request, {'form' : form})
  119
+        return HttpResponse(t.render(c))
  120
+
  121
+(This view, as well as all the following ones, have the same imports as the
  122
+first example above does.)
  123
+
  124
+The ``formfields.FormWrapper`` object is a wrapper that templates can
  125
+easily deal with to create forms; here's the ``naive_create_form`` template::
  126
+
  127
+    {% extends "base" %}
  128
+    
  129
+    {% block content %}
  130
+    <h1>Create a place:</h1>
  131
+    
  132
+    <form method="post" action="../do_new/">
  133
+    <p><label for="id_name">Name:</label> {{ form.name }}</p>
  134
+    <p><label for="id_address">Address:</label> {{ form.address }}</p>
  135
+    <p><label for="id_city">City:</label> {{ form.city }}</p>
  136
+    <p><label for="id_state">State:</label> {{ form.state }}</p>
  137
+    <p><label for="id_zip_code">Zip:</label> {{ form.zip_code }}</p>
  138
+    <p><label for="id_place_type">Place type:</label> {{ form.place_type }}</p>
  139
+    <input type="submit" />
  140
+    </form>
  141
+    {% endblock %}
  142
+    
  143
+Before we get back to the problems with these naive set of views, let's go over 
  144
+some salient points of the above template::
  145
+
  146
+    * Field "widgets" are handled for you: ``{{ form.field }}`` automatically
  147
+      creates the "right" type of widget for the form, as you can see with the
  148
+      ``place_type`` field above.
  149
+    
  150
+    * There isn't a way just to spit out the form; you'll still need to define
  151
+      how the form gets laid out.  This is a feature: every form needs to be
  152
+      designed differently; Django doesn't force you into any type of mould.
  153
+      If you must use tables, use tables; if you're a semantic purist you can
  154
+      probably find better HTML than the above template.
  155
+
  156
+    * To avoid name conflicts, the ``id``s of form elements take the form 
  157
+      "id_*fieldname*".
  158
+    
  159
+By creating a creation form we've solved problem number 3 above, but we still don't
  160
+have any validation; if you enter bad data into any of the .  Let's revise the validation
  161
+issue by writing a new creation view that takes into account validation::
  162
+
  163
+    def create_place_with_validation(request):
  164
+        manipulator = places.AddManipulator()
  165
+        new_data = request.POST.copy()
  166
+        
  167
+        # Check for validation errors
  168
+        errors = manipulator.get_validation_errors(new_data)
  169
+        if errors:
  170
+            t = template_loader.get_template('places/errors')
  171
+            c = Context(request, {'errors' : errors}
  172
+            return HttpResponse(t.render(c))
  173
+        else:
  174
+            manipulator.do_html2python(request.POST)
  175
+            new_place = manipulator.save(request.POST)
  176
+            return HttpResponse("Place created: %s" % new_place)
  177
+
  178
+In this new version, errors will be found -- ``manipulator.get_validation_errors``
  179
+handles all the validation for you -- and those errors can be nicely presented
  180
+on an error page (templated, of course)::
  181
+
  182
+    {% extends "base" %}
  183
+    
  184
+    {% block content %}
  185
+    
  186
+    <h1>Please go back and correct the following error{{ errors|pluralize }}:</h1>
  187
+    <ul>
  188
+        {% for e in errors.items %}
  189
+        <li>Field "{{ e.0 }}": {{ e.1|join:", " }}</li>
  190
+        {% endfor %}
  191
+    </ul>
  192
+    
  193
+    {% endblock %}
  194
+
  195
+Still, this now has its own problems:
  196
+
  197
+    * There's still the issue of creating a seperate (redundant) view for the
  198
+      submission form.
  199
+      
  200
+    * Errors, though nicely presented are on a seperate page, so the user will have
  201
+      to use the "back" button to fix errors -- not exactly usable!
  202
+
  203
+The best way to deal with these issues is to collapse the two views -- the form and the
  204
+submission -- into a single view.  This view will be responsible for creating the
  205
+form, validating POSTed data, and creating the new object (should it the data be
  206
+valid).  An added bonus of this approach is that errors and the form will both
  207
+be available on the same page, so errors with fields can be presented in context.
  208
+
  209
+.. admonition:: Philosophy::
  210
+
  211
+    Finally, for the HTTP purists in the audience (and the authorship), this
  212
+    nicely matches the "true" meanings of HTTP-GET and HTTP-POST: GET fetches
  213
+    the form, POST creates the new object.
  214
+
  215
+Below is the finished view::
  216
+
  217
+    def create_place(request):
  218
+        manipulator = places.AddManipulator()
  219
+        
  220
+        if request.POST:
  221
+            # If data was POSTed, we're trying to create a new Place
  222
+            new_data = request.POST.copy()
  223
+            
  224
+            # Check for errors
  225
+            errors = manipulator.get_validation_errors(new_data)
  226
+            
  227
+            if not errors:
  228
+                # No errors -- this means we can save the data!
  229
+                manipulator.do_html2python(new_data)
  230
+                new_place = manipulator.save(new_data)
  231
+                
  232
+                # Redirect to the object's "edit" page (so that reloads
  233
+                # don't accidentally create duplicate entries)
  234
+                return HttpResponseRedirect("/places/edit/%i/" % new_place.id)
  235
+        else:
  236
+            # No POST, so we want a brand new form without any data or errors
  237
+            errors = new_data = {}
  238
+        
  239
+        # Create the FormWrapper, template, context, response
  240
+        form = formfields.FormWrapper(manipulator, new_data, errors)
  241
+        t = template_loader.get_template("places/create_form")
  242
+        c = Context(request, {
  243
+            'form' : form, 
  244
+        })
  245
+        return HttpResponse(t.render(c))
  246
+
  247
+and here's the ``create_form`` template::
  248
+
  249
+    {% extends "base" %}
  250
+    
  251
+    {% block content %}
  252
+    <h1>Create a place:</h1>
  253
+    
  254
+    {% if form.has_errors %}
  255
+    <h2>Please correct the following error{{ errors|pluralize }}:</h2>
  256
+    {% endif %}
  257
+    
  258
+    <form method="post" action=".">
  259
+    <p>
  260
+        <label for="id_name">Name:</label> {{ form.name }} 
  261
+        {% if form.name.errors %}*** {{ form.name.errors|join:", " }}{% endif %}
  262
+    </p>
  263
+    <p>
  264
+        <label for="id_address">Address:</label> {{ form.address }}
  265
+        {% if form.address.errors %}*** {{ form.address.errors|join:", " }}{% endif %}
  266
+    </p>
  267
+    <p>
  268
+        <label for="id_city">City:</label> {{ form.city }}
  269
+        {% if form.city.errors %}*** {{ form.city.errors|join:", " }}{% endif %}
  270
+    </p>
  271
+    <p>
  272
+        <label for="id_state">State:</label> {{ form.state }}
  273
+        {% if form.state.errors %}*** {{ form.state.errors|join:", " }}{% endif %}
  274
+    </p>
  275
+    <p>
  276
+        <label for="id_zip_code">Zip:</label> {{ form.zip_code }}
  277
+        {% if form.zip_code.errors %}*** {{ form.zip_code.errors|join:", " }}{% endif %}
  278
+    </p>
  279
+    <p>
  280
+        <label for="id_place_type">Place type:</label> {{ form.place_type }}
  281
+        {% if form.place_type.errors %}*** {{ form.place_type.errors|join:", " }}{% endif %}
  282
+    </p>
  283
+    <input type="submit" />
  284
+    </form>
  285
+    {% endblock %}
  286
+
  287
+The second two arguments to ``FormWrapper`` (``new_data`` and ``errors``)
  288
+deserve some mention.
  289
+
  290
+The first is any "default" data to be used as values for the fields; pulling the
  291
+data from ``request.POST`` as is done above makes sure that if there are errors,
  292
+the values the user put in aren't lost. If you try the above example, you'll see
  293
+this in action.
  294
+
  295
+The second argument is the error list retrieved from
  296
+``manipulator.get_validation_errors``.  When passed into the ``FormWrapper``, this gives
  297
+each field an ``errors`` item (which is a list of error messages associated with the
  298
+field) as well as a ``html_error_list`` item which is a ``<ul>`` of error messages.
  299
+The above template uses these error items to display a simple error message next
  300
+to each field.
  301
+
  302
+Using the ``ChangeManipulator``
  303
+-------------------------------
  304
+
  305
+So: the above has covered using the ``AddManipulator`` to create a new object;
  306
+what about editing an existing one?  It's rather shockingly similar to creating
  307
+a new one::
  308
+
  309
+    def edit_place(request, place_id):
  310
+        # Get the place in question from the database and create a ChangeManipulator 
  311
+        # at the same time
  312
+        try:
  313
+            manipulator = places.ChangeManipulator(place_id)
  314
+        except places.PlaceDoesNotExist:
  315
+            raise Http404
  316
+        
  317
+        # Grab the Place object is question for future use
  318
+        place = manipulator.original_object
  319
+        
  320
+        if request.POST:
  321
+            new_data = request.POST.copy()
  322
+            errors = manipulator.get_validation_errors(new_data)
  323
+            if not errors:
  324
+                manipulator.do_html2python(new_data)
  325
+                manipulator.save(new_data)
  326
+                
  327
+                # Do a post-after-redirect so that reload works, etc.
  328
+                return HttpResponseRedirect("/places/edit/%i/" % place.id)
  329
+        else:
  330
+            errors = {}
  331
+            # This makes sure the form accurate represents the fields of the place.
  332
+            new_data = place.__dict__
  333
+        
  334
+        form = formfields.FormWrapper(manipulator, new_data, errors)
  335
+        t = template_loader.get_template("places/edit_form")
  336
+        c = Context(request, {
  337
+            'form' : form, 
  338
+            'place' : place,
  339
+        })
  340
+        return HttpResponse(t.render(c))
  341
+    
  342
+The only real differences here are:
  343
+
  344
+    * A ``ChangeManipulator`` instead of an ``AddManipulator`` is created; 
  345
+      The argument to any ``ChangeManipulator`` is the id of the object
  346
+      to be changed.  As you can see, the initializer will raise an
  347
+      ``ObjectDoesNotExist`` exception if the id is invalid.
  348
+      
  349
+    * ``ChangeManipulator.original_object`` stores the instance of the
  350
+      object being edited.
  351
+      
  352
+    * We set ``new_data`` to the original object's ``__dict__``; this makes
  353
+      sure that the form fields contain the current values of the object.
  354
+      ``FormWrapper`` does not modify ``new_data`` in any way, and templates
  355
+      cannot, so this is perfectly safe.
  356
+      
  357
+    * The above example uses a different template so that create and edit can
  358
+      be "skinned" differently if needed, but the form chunk itself is
  359
+      completely identical to the one in the create form above.
  360
+      
  361
+The astute programmer will notice that the add and create functions are nearly 
  362
+identical and could in fact be collapsed into a single view; this is left
  363
+as an exercise for said programmer.
  364
+
  365
+(However, the even-more-astute programmer will take heed of the note at the top
  366
+of this document and check out the `generic views`_ documentation if all she
  367
+wishes to do is this type of simple create/update).
  368
+
  369
+Custom forms and manipulators
  370
+=============================
  371
+
  372
+All the above is fine and dandy if you want to just use the automatically created
  373
+manipulators, but the coolness doesn't end there: you can easily create your 
  374
+own custom manipulators for handling custom forms.
  375
+
  376
+Custom manipulators are pretty simple; here's a manipulator that you might use
  377
+for a "contact" form on a website::
  378
+
  379
+    from django.core import formfields
  380
+    
  381
+    urgency_choices = (
  382
+        (1, "Extremely urgent"),
  383
+        (2, "Urgent"),
  384
+        (3, "Normal"),
  385
+        (4, "Unimportant"),
  386
+    )
  387
+    
  388
+    class ContactManipulator(formfields.Manipulator):
  389
+        def __init__(self):
  390
+            self.fields = (
  391
+                formfields.EmailField(field_name="from", is_required=True),
  392
+                formfields.TextField(field_name="subject", length=30, maxlength=200, is_required=True),
  393
+                formfields.IntegerField(field_name="urgency", choices=urgency_choices),
  394
+                formfields.LargeTextField(field_name="contents", is_required=True),
  395
+            )
  396
+            
  397
+A certain similarity to Django's models should be apparent.  The only required
  398
+method of a custom manipulator is ``__init__`` which must define the fields
  399
+present in the manipulator.  See the ``django.core.formfields`` module for
  400
+all the form fields provided by Django.
  401
+
  402
+You use this custom manipulator exactly as you would use an auto-generated one;
  403
+here's a simple function that might drive the above form::
  404
+
  405
+    def contact_form(request):
  406
+        manipulator = ContactFormManipulator()
  407
+        if request.POST:
  408
+            new_data = request.POST.copy()
  409
+            errors = manipulator.get_validation_errors(new_data)
  410
+            if not errors:
  411
+                manipulator.do_html2python(new_data)
  412
+                
  413
+                # send email using new_data here...
  414
+                
  415
+                return HttpResponseRedirect("/contact/thankyou/")
  416
+        else:
  417
+            errors = new_data = {}
  418
+        form = formfields.FormWrapper(manipulator, new_data, errors)
  419
+        t = template_loader.get_template("contact_form")
  420
+        c = Context(request, {
  421
+            'form' : form, 
  422
+        })
  423
+        return HttpResponse(t.render(c))
  424
+
  425
+Validators
  426
+==========
  427
+
  428
+One extremely useful feature of manipulators is the automatic validation it
  429
+performs. Validation is done using a simple validation API: a validator is
  430
+simple a callable that raises a ``ValidationError`` if there's something wrong
  431
+with the data. ``django.core.validators`` defines a whole host of validator
  432
+functions, but defining your own couldn't be easier::
  433
+
  434
+    from django.core import validators, formfields
  435
+
  436
+    class ContactManipulator(formfields.Manipulator):
  437
+        def __init__(self):
  438
+            self.fields = (
  439
+                # ... snip fields as above ...
  440
+                formfields.EmailField(field_name="to", validator_list=[self.isValidToAddress])
  441
+            )
  442
+            
  443
+        def isValidToAddress(self, field_data, all_data):
  444
+            if not field_data.endswith("@example.com"):
  445
+                raise ValidationError("You can only send messages to example.com email addresses")
  446
+                
  447
+Above, we've added a "to" field to the contact form, but required that the 
  448
+"to" address end with "@example.com" by adding the ``isValidToAddress``
  449
+validator to the field's ``validator_list``.
  450
+
  451
+The arguments to a validator function take a little explanation.  ``field_data``
  452
+is the value of the field in question, and ``all_data`` is a dict of all the
  453
+data being validated.  Note that at the point validators are called all data
  454
+will still be strings (as ``do_html2python`` hasn't been called yet).
  455
+
  456
+.. _`generic views`: http://www.djangoproject.com/documentation/generic_views/

0 notes on commit 8bd30b0

Please sign in to comment.
Something went wrong with that request. Please try again.