Added MultipleFileField instead of having a 'multiple' option on FileField

Only set form.files onChange if the input has a 'files' property

Set an array or single file based on type of FileField

Browser: retrieval of FileField data from input now falls back to data if not present in files

Related to #61

Author: insin

docs/fields.rst

@@ -351,6 +351,7 @@ Built-in Field type hierarchy
   * :ref:`FileField <ref-fields-FileField>`
 
     * :ref:`ImageField <ref-fields-ImageField>`
+    * :ref:`MultipleFileField <ref-fields-MultipleFileField>`
   * :ref:`MultiValueField <ref-fields-MultiValueField>`
 
     * :ref:`SplitDateTimeField <ref-fields-SplitDateTimeField>`
@@ -580,8 +581,12 @@ Build-in Fields (A-Z)
 
    * Default widget: :js:class:`ClearableFileInput`
    * Empty value: ``null``
-   * Normalises to: The given object in ``files`` - this field just validates
-     what's there and leaves the rest up to you.
+   * Normalises to:
+
+     * Client: a native `File`_ object, when supported by the browser, otherwise
+       the ``value`` of the ``<input type="file">``.
+     * Server: the given object in ``files`` - this field just validates
+       what's there and leaves the rest up to you.
    * Can validate that non-empty file data has been bound to the form.
    * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``,
      ``maxLength``
@@ -767,6 +772,31 @@ Build-in Fields (A-Z)
 
    Takes one extra required argument, ``choices``, as for ``ChoiceField``.
 
+.. _ref-fields-MultipleFileField:
+
+:js:class:`MultipleFileField`
+-----------------------------
+
+.. versionadded:: 0.11
+
+   * Default widget: :js:class:`FileInput` with ``multiple`` attribute
+   * Empty value: ``[]`` (an empty list)
+   * Normalises to:
+
+     * Client: a list of `File`_ objects, when supported by the browser,
+       otherwise the ``value`` of the ``<input type="file" multiple>``.
+     * Server: the given object in ``files`` - this field just validates
+       what's there and leaves the rest up to you.
+   * Can validate that non-empty file data has been bound to the form.
+   * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``,
+     ``maxLength``
+
+   The ``empty`` and ``maxLength`` error messages may contain ``{name}``, which
+   will be replaced with the name of the file which failed validation.
+
+   Has two optional arguments for validation, ``maxLength`` and
+   ``allowEmptyFile`` as for ``FileField``.
+
 .. _ref-fields-TypedMultipleChoiceField:
 
 :js:class:`TypedMultipleChoiceField`
@@ -1050,4 +1080,5 @@ requirements are that it implement a ``clean()`` method and that its
 (``required``, ``label``, ``initial``, ``widget``, ``helpText``) in an argument
 object.
 
+.. _`File`: https://developer.mozilla.org/en-US/docs/Web/API/File
 .. _`format strings`: https://github.com/insin/isomorph#formatting-directives

docs/fields_api.rst

@@ -284,12 +284,19 @@ File fields
 
 .. js:class:: FileField([kwargs])
 
-   Validates that its input is a valid uploaded file -- the behaviour of this
-   field varies depending on the environmnet newforms is running in:
+   Validates that its input is a valid file -- the behaviour of this field
+   varies depending on the environmnet newforms is running in:
 
    **On the client**
 
-      Validates that a file has been selected if the field is ``required``.
+      If the browser supports the `File API <http://www.w3.org/TR/FileAPI/>`_,
+      ``form.files`` will be populated with a
+      `File <https://developer.mozilla.org/en-US/docs/Web/API/File>`_ object and
+      validation will be performed on its name and size. The ``File`` object
+      will be available via ``form.cleanedData`` when valid.
+
+      Otherwise, this field can only validate that a file has been selected at
+      all, if the field is ``required```.
 
    **On the server**
 
@@ -311,6 +318,14 @@ File fields
    :param Boolean kwargs.allowEmptyFile:
       if ``true``, empty files will be allowed -- defaults to ``false``.
 
+.. js:class:: MultipleFileField([kwargs])
+
+   A version of FileField which expects to receive a list of files as input and
+   renders to an ``<input type="file" multiple>`` by default.
+
+   :param Object kwargs:
+     field options, as in :js:class:`FileField`
+
 .. js:class:: ImageField([kwargs])
 
    Validates that its input is a valid uploaded image -- the behaviour of this

docs/forms.rst

@@ -872,18 +872,34 @@ form its own namespace, use the ``prefix`` argument:
    </div>
    */
 
-.. _binding-uploaded-files:
+Client: Working with files
+==========================
 
-Binding uploaded files to a form
-================================
+If your browser implements the `File API <http://www.w3.org/TR/FileAPI>`_,
+``form.cleanedData`` will contain native
+`File <https://developer.mozilla.org/en-US/docs/Web/API/File>`_ objects for any
+``FileField``, ``MultipleFileField`` and ``ImageField`` fields in your form.
 
-.. Warning::
-   Since handling of file uploads in single page apps is a little bit different
-   than a regular multipart form submission, this section isn't worth much! This
-   subject will be revisited in a future release.
+While these fields are only currently capable of performing limited validation,
+having access to ``File`` objects allows you to more easily implement your own
+validation based on file size, type and contents at whichever of the available
+:ref:`validation steps <ref-validation-steps-and-order>` is most appropriate for
+your needs.
 
-Dealing with forms that have ``FileField`` and ``ImageField`` fields
-is a little more complicated than a normal form.
+Server: Binding uploaded files to a form
+========================================
+
+.. Note::
+   This section deals with a very specific use case: using React to render
+   forms, but performing and subsequently handling regular form submissions.
+
+   This may only be relevant if you're using React purely for server-side
+   rendering, or you're creating an isomorphic app which progressively enhances
+   regular form submissions.
+
+Dealing with forms that have ``FileField``, ``MultipleFileField`` or
+``ImageField`` fields and will be submitted via a regular form POST is a little
+more complicated than a regular form.
 
 Firstly, in order to upload files, you'll need to make sure that your
 ``<form>`` element correctly defines the ``enctype`` as
@@ -896,7 +912,7 @@ Firstly, in order to upload files, you'll need to make sure that your
 Secondly, when you use the form, you need to bind the file data. File
 data is handled separately to normal form data, so when your form
 contains a ``FileField`` and ``ImageField``, you will need to specify
-a ``files`` argument when you bind your form. So if we extend our
+a ``files`` argument when creating a form instance. So if we extend our
 ContactForm to include an ``ImageField`` called ``mugshot``, we
 need to bind the file data containing the mugshot image:
 
@@ -912,9 +928,10 @@ need to bind the file data containing the mugshot image:
    var fileData = {mugshot: {name: 'face.jpg', size: 123456}}
    var f = new ContactFormWithMugshot({data: data, files: fileData})
 
-Assuming that you're using `Express`_ and its ``bodyParser()`` on the server
-side, you will usually specify ``req.files`` as the source of file data (just
-like you'd use ``req.body`` as the source of form data):
+Assuming you're using `Express`_, or a similar library which supports middleware
+for processing file uploads, you will usually specify ``req.files`` as the
+source of file data (just like you'd use ``req.body`` as the source of form
+data):
 
 ..  code-block:: javascript
 

docs/validation.rst

@@ -18,6 +18,8 @@ easily. Validators are functions that take a single argument and throw a
 ``ValidationError`` on invalid input. Validators are run after the field's
 ``toJavaScript()`` and ``validate()`` methods have been called.
 
+.. _ref-validation-steps-and-order:
+
 Validation steps and order
 ==========================
 

src/Form.js

@@ -13,6 +13,7 @@ var DeclarativeFieldsMeta = require('./forms/DeclarativeFieldsMeta')
 var ErrorList = require('./ErrorList')
 var ErrorObject = require('./ErrorObject')
 var FileField = require('./fields/FileField')
+var MultipleFileField = require('./fields/MultipleFileField')
 
 var {ValidationError} = require('validators')
 var {cancellable, debounce, info, warning, normaliseValidation} = require('./util')
@@ -575,9 +576,11 @@ Form.prototype._handleFieldEvent = function(validation, e) {
   var field = this.fields[fieldName]
   var targetData = getFormData.getNamedFormElementData(e.target.form, htmlName)
   this.data[htmlName] = targetData
-  if (field instanceof FileField) {
+  if (field instanceof FileField && 'files' in e.target) {
     var files = e.target.files
-    this.files[htmlName] = field.multiple ? Array.prototype.slice.call(files) : files[0]
+    this.files[htmlName] = (field instanceof MultipleFileField
+                            ? Array.prototype.slice.call(files)
+                            : files[0])
   }
   if (this.isInitialRender) {
     this.isInitialRender = false

src/fields/FileField.js

@@ -28,53 +28,44 @@ var FileField = Field.extend({
 
 , constructor: function FileField(kwargs) {
     if (!(this instanceof FileField)) { return new FileField(kwargs) }
-    kwargs = object.extend({maxLength: null, allowEmptyFile: false, multiple: false}, kwargs)
+    kwargs = object.extend({maxLength: null, allowEmptyFile: false}, kwargs)
     this.maxLength = kwargs.maxLength
     this.allowEmptyFile = kwargs.allowEmptyFile
-    this.multiple = kwargs.multiple
     delete kwargs.maxLength
     Field.call(this, kwargs)
   }
 })
 
-FileField.prototype.getWidgetAttrs = function(widget) {
-  var attrs = Field.prototype.getWidgetAttrs.call(this, widget)
-  attrs.multiple = this.multiple
-  return attrs
-}
-
 FileField.prototype.toJavaScript = function(data, initial) {
   if (this.isEmptyValue(data)) {
     return null
   }
 
   // If the browser doesn't support File objects, we can't do anything more
-  if (env.browser && (is.String(data) || is.Array(data) && is.String(data[0]))) {
+  if (env.browser && is.String(data)) {
     return data
   }
 
-  ;[].concat(data).forEach(function(file) {
-    // File objects should have name and size attributes
-    if (typeof file.name == 'undefined' || typeof file.size == 'undefined') {
-      throw ValidationError(this.errorMessages.invalid, {code: 'invalid'})
-    }
+  // File objects should have name and size attributes
+  if (typeof data.name == 'undefined' || typeof data.size == 'undefined') {
+    throw ValidationError(this.errorMessages.invalid, {code: 'invalid'})
+  }
 
-    var fileName = file.name
-    var fileSize = Number(file.size)
+  var name = data.name
+  var suze = Number(data.size)
 
-    if (this.maxLength !== null && fileName.length > this.maxLength) {
-      throw ValidationError(this.errorMessages.maxLength, {
-        code: 'maxLength'
-      , params: {max: this.maxLength, length: fileName.length}
-      })
-    }
-    if (!fileName) {
-      throw ValidationError(this.errorMessages.invalid, {code: 'invalid'})
-    }
-    if (!this.allowEmptyFile && fileSize === 0) {
-      throw ValidationError(this.errorMessages.empty, {code: 'empty'})
-    }
-  }.bind(this))
+  if (this.maxLength !== null && name.length > this.maxLength) {
+    throw ValidationError(this.errorMessages.maxLength, {
+      code: 'maxLength'
+    , params: {max: this.maxLength, length: name.length}
+    })
+  }
+  if (!name) {
+    throw ValidationError(this.errorMessages.invalid, {code: 'invalid'})
+  }
+  if (!this.allowEmptyFile && suze === 0) {
+    throw ValidationError(this.errorMessages.empty, {code: 'empty'})
+  }
 
   return data
 }

src/fields/MultipleFileField.js

@@ -0,0 +1,99 @@
+'use strict';
+
+var is = require('isomorph/is')
+
+var env = require('../env')
+
+var Field = require('../Field')
+var FileInput = require('../widgets/FileInput')
+var FileField = require('./FileField')
+
+var {ValidationError} = require('validators')
+
+/**
+ * Validates that its input is a list of valid files.
+ * @constructor
+ * @extends {FileField}
+ * @param {Object=} kwargs
+ */
+var MultipleFileField = FileField.extend({
+  widget: FileInput,
+
+  defaultErrorMessages: {
+    invalid: 'No files were submitted. Check the encoding type on the form.',
+    missing: 'No files were submitted.',
+    empty: '{name} is empty.',
+    maxLength: 'Ensure filenames have at most {max} characters ({name} has {length}).'
+  },
+
+  constructor: function MultipleFileField(kwargs) {
+    if (!(this instanceof MultipleFileField)) { return new MultipleFileField(kwargs) }
+    FileField.call(this, kwargs)
+  }
+})
+
+MultipleFileField.prototype.getWidgetAttrs = function(widget) {
+  var attrs = FileField.prototype.getWidgetAttrs.call(this, widget)
+  attrs.multiple = true
+  return attrs
+}
+
+MultipleFileField.prototype.toJavaScript = function(data, initial) {
+  if (this.isEmptyValue(data)) {
+    return []
+  }
+
+  // If the browser doesn't support File objects, we can't do anything more
+  if (env.browser && is.String(data)) {
+    return data
+  }
+
+  for (var i = 0, l = data.length; i < l; i++) {
+    var file = data[i]
+
+    // File objects should have name and size attributes
+    if (typeof file.name == 'undefined' || typeof file.size == 'undefined') {
+      throw ValidationError(this.errorMessages.invalid, {code: 'invalid'})
+    }
+
+    var name = file.name
+    var size = Number(file.size)
+
+    if (this.maxLength !== null && name.length > this.maxLength) {
+      throw ValidationError(this.errorMessages.maxLength, {
+        code: 'maxLength',
+        params: {max: this.maxLength, name, length: name.length}
+      })
+    }
+    if (!name) {
+      throw ValidationError(this.errorMessages.invalid, {code: 'invalid'})
+    }
+    if (!this.allowEmptyFile && size === 0) {
+      throw ValidationError(this.errorMessages.empty, {
+        code: 'empty',
+        params: {name}
+      })
+    }
+  }
+
+  return data
+}
+
+MultipleFileField.prototype.clean = function(data, initial) {
+  if (this.isEmptyValue(data) && !this.isEmptyValue(initial)) {
+    return initial
+  }
+  return Field.prototype.clean.call(this, data)
+}
+
+MultipleFileField.prototype.validate = function(value) {
+  if (this.required && !value.length) {
+    throw ValidationError(this.errorMessages.required, {code: 'required'})
+  }
+}
+
+MultipleFileField.prototype._hasChanged = function(initial, data) {
+  return !this.isEmptyValue(data)
+}
+
+module.exports = MultipleFileField

src/newforms.js

@@ -51,6 +51,7 @@ module.exports = {
 , isFormAsync: require('./forms/isFormAsync')
 , locales: locales
 , MultipleChoiceField: require('./fields/MultipleChoiceField')
+, MultipleFileField: require('./fields/MultipleFileField')
 , MultipleHiddenInput: require('./widgets/MultipleHiddenInput')
 , MultiValueField: require('./fields/MultiValueField')
 , MultiWidget: require('./widgets/MultiWidget')