@@ -710,6 +710,47 @@ For example::
710710 </ul>
711711 </form>
712712
713+ Binding uploaded files to a form
714+ --------------------------------
715+
716+ Dealing with forms that have ``FileField`` and ``ImageField`` fields
717+ is a little more complicated than a normal form.
718+
719+ Firstly, in order to upload files, you'll need to make sure that your
720+ ``<form>`` element correctly defines the ``enctype`` as
721+ ``"multipart/form-data"``::
722+
723+ <form enctype="multipart/form-data" method="post" action="/foo/">
724+
725+ Secondly, when you use the form, you need to bind the file data. File
726+ data is handled separately to normal form data, so when your form
727+ contains a ``FileField`` and ``ImageField``, you will need to specify
728+ a second argument when you bind your form. So if we extend our
729+ ContactForm to include an ``ImageField`` called ``mugshot``, we
730+ need to bind the file data containing the mugshot image::
731+
732+ # Bound form with an image field
733+ >>> data = {'subject': 'hello',
734+ ... 'message': 'Hi there',
735+ ... 'sender': 'foo@example.com',
736+ ... 'cc_myself': True}
737+ >>> file_data = {'mugshot': {'filename':'face.jpg'
738+ ... 'content': <file data>}}
739+ >>> f = ContactFormWithMugshot(data, file_data)
740+
741+ In practice, you will usually specify ``request.FILES`` as the source
742+ of file data (just like you use ``request.POST`` as the source of
743+ form data)::
744+
745+ # Bound form with an image field, data from the request
746+ >>> f = ContactFormWithMugshot(request.POST, request.FILES)
747+
748+ Constructing an unbound form is the same as always -- just omit both
749+ form data *and* file data:
750+
751+ # Unbound form with a image field
752+ >>> f = ContactFormWithMugshot()
753+
713754Subclassing forms
714755-----------------
715756
@@ -1099,6 +1140,50 @@ Has two optional arguments for validation, ``max_length`` and ``min_length``.
10991140If provided, these arguments ensure that the string is at most or at least the
11001141given length.
11011142
1143+ ``FileField``
1144+ ~~~~~~~~~~~~~
1145+
1146+ * Default widget: ``FileInput``
1147+ * Empty value: ``None``
1148+ * Normalizes to: An ``UploadedFile`` object that wraps the file content
1149+ and file name into a single object.
1150+ * Validates that non-empty file data has been bound to the form.
1151+
1152+ An ``UploadedFile`` object has two attributes:
1153+
1154+ ====================== =====================================================
1155+ Argument Description
1156+ ====================== =====================================================
1157+ ``filename`` The name of the file, provided by the uploading
1158+ client.
1159+ ``content`` The array of bytes comprising the file content.
1160+ ====================== =====================================================
1161+
1162+ The string representation of an ``UploadedFile`` is the same as the filename
1163+ attribute.
1164+
1165+ When you use a ``FileField`` on a form, you must also remember to
1166+ `bind the file data to the form`_.
1167+
1168+ .. _`bind the file data to the form`: `Binding uploaded files to a form`_
1169+
1170+ ``ImageField``
1171+ ~~~~~~~~~~~~~~
1172+
1173+ * Default widget: ``FileInput``
1174+ * Empty value: ``None``
1175+ * Normalizes to: An ``UploadedFile`` object that wraps the file content
1176+ and file name into a single object.
1177+ * Validates that file data has been bound to the form, and that the
1178+ file is of an image format understood by PIL.
1179+
1180+ Using an ImageField requires that the `Python Imaging Library`_ is installed.
1181+
1182+ When you use a ``FileField`` on a form, you must also remember to
1183+ `bind the file data to the form`_.
1184+
1185+ .. _Python Imaging Library: http://www.pythonware.com/products/pil/
1186+
11021187``IntegerField``
11031188~~~~~~~~~~~~~~~~
11041189
@@ -1378,11 +1463,11 @@ the full list of conversions:
13781463 ``DateTimeField`` ``DateTimeField``
13791464 ``DecimalField`` ``DecimalField``
13801465 ``EmailField`` ``EmailField``
1381- ``FileField`` ``CharField ``
1466+ ``FileField`` ``FileField ``
13821467 ``FilePathField`` ``CharField``
13831468 ``FloatField`` ``FloatField``
13841469 ``ForeignKey`` ``ModelChoiceField`` (see below)
1385- ``ImageField`` ``CharField ``
1470+ ``ImageField`` ``ImageField ``
13861471 ``IntegerField`` ``IntegerField``
13871472 ``IPAddressField`` ``CharField``
13881473 ``ManyToManyField`` ``ModelMultipleChoiceField`` (see
0 commit comments