file-input.html

<link rel="import" href="../polymer/polymer.html">
<script src="file-input.js"></script>

<!--
A better `<input type="file">`.

### What's wrong with `<input type="file">`?

1. It's difficult to skin/style as the look and feel of the element is mostly determined by the user agent.
2. Access to the selected files are provided via `FileList` object, which is a pseudo-array (not a "real" array, with useful sugar like `forEach`, etc).
3. You want any sort of file validation?  Do it yourself!
4. The API is lacking in many respects.

Now, a new, better, evolved (and evolving) element to take its place: `<file-input>`!

#### `<file-input>` integrates perfectly with `<ajax-form>`!
Simply include a `<file-input>` in [an `<ajax-form>`](https://github.com/garstasio/ajax-form), 
ensure the `name` attribute is present on the `<file-input>`, and the `<ajax-form>` 
includes an `enctype` attriute with a value of `multipart/form-data`.  Any valid 
files will be sent along with the other form fields!  

If you incoude a `required` attribute on the `<file-input>`, `<ajax-form>` will 
even prevent the form from being submitted if there isn't at least one valid 
file selected!  Note that the validation of custom elements, such as `<file-input>`,
will first be possible in [`<ajax-form>` 1.3.0](https://github.com/garstasio/ajax-form/issues/6).

__Don't forget to [vulcanize](http://www.polymer-project.org/articles/concatenating-web-components.html)
your main/parent HTML file before deploying into production.  This will ensure
that all of your HTML imports are concatenated into one file.__

@element file-input
@status beta
@homepage index.html
-->

<polymer-element name="file-input" attributes="accept camera directory extensions maxFiles maxSize minSize required">

    <template>

        <style>
            :host {
                position: relative;
            }

            #fileInput {
                bottom: 0;
                height: 100%;
                left: 0;
                margin: 0;
                opacity: 0;
                padding: 0;
                position: absolute;
                right: 0;
                top: 0;
                width: 100%;
            }
        </style>

        <content></content>

        <input
            accept="{{accept}}"
            id="fileInput"
            on-change="{{changeHandler}}"
            type="file"
        >

    </template>

    <script>
        /**
        * When your user selects new files, a "change" event will be triggered 
        * on the element.  The `detail` property on the `event` passed to your 
        * handler will contain two properties: `valid` and `invalid`.  
        * These correspond to the `files` and `invalid` (respectively) 
        * properties on the element instance.
        *
        *     fileInputEl.addEventListener("change", 
        *         function(event) {
        *             var validFiles = event.detail.valid,
        *                 invalidFiles = event.detail.invalid;
        *
        *             // handle the event
        *         }
        *     );
        * 
        * @event change
        */
        
        /**
        * To access an `Array` of `File` objects selected by your user that have also passed all validation checks, look to the `files` property.
        * 
        *     var validFiles = fileInputElement.files;
        * 
        * @property files
        * @type Array
        * @default []
        */
        
        /**
        * To access an `Object` containing keyed `Array`s of `File` objects, 
        * representing any files selected by your user that did **not** 
        * pass validation checks, inspect the `invalid` property.  
        *
        * This is an object with a `count` property to easily determine how 
        * many invalid files exist.  Invalid files are grouped by reason.  
        * For example, if there are 4 invalid files, one of each type: 
        * the value of the `invalid` property would look like this:
        *
        *     var invalidFiles = fileInputEl.invalid;
        * 
        *     expect(invalidFiles).toEqual({
        *         count: 4,
        * 
        *         // array containing the 1 file 
        *         // with a bad extension
        *         badExtension: [],
        * 
        *         // array containing the 1 file with 
        *         // a file size that was too large
        *         tooBig: [], 
        * 
        *         // array containing the 1 file with 
        *         // a file size that was too small
        *         tooSmall: [],
        *
        *         // array containing any leftover 
        *         // otherwise valid files that exceed 
        *         // the number of allowable files 
        *         tooMany: []
        *     });
        *
        * 
        * @property invalid
        * @type Object
        * @default {count: 0}
        */

        /**
         * To reset the `files` and `invalid` cache and also reset the
         * underlying `<input type="file">`, use the `reset()` function:
         *
         *     document.querySelector("file-input").reset();
         * 
         * @method reset
         */

        /**
         * If you want to restrict the types of files that the file chooser 
         * will allow your user's to select, you can make use of an `accept` 
         * attribute, passing one or more MIME types as comma-separated values.  
         * Please note that [browser support for this attribute is poor and implementations vary](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input#Browser_compatibility).  
         * 
         * For example, to only allow your users to select images and videos:  
         *
         *     <file-input accept="image/*,video/*">
         *         Select Files
         *     </file-input>
         * 
         * @attribute accept
         * @type string
         */
         
         /**
          * This is currently an iOS-specific attribute, as there are a few
          * attributes on the underlying `<input type="file">` element that must
          * be setup in order to allow camera access on Apple mobile devices.
          * `<file-input>` is smart enough to only apply these settings when
          * neceessary (only when the device is running iOS), so including this
          * property on other devices is essentially a NOP.
          * 
          *     <file-input camera>
          *         Select Files
          *     </file-input>
          *
          * @attribute camera
          */

         /**
          * Some browsers (currently only Chrome and Opera) allow you to 
          * select folders for upload.  To turn on this feature (ignored 
          * if not supported by the UA), just include this attribute 
          * on the element.
          * 
          *     <file-input directory>
          *         Select Files
          *     </file-input>
          *
          * Note: Using this feature may not be a great idea for 
          * large directories (or high-latency file systems) since the UI thread 
          * is blocked while the file tree is parsed.  This is an unfortunate 
          * native implementation detail in the browser.
          *
          * 
          * @attribute directory
          */
          
          /**
           * Text that will appear next to the element if an `<ajax-form>` 
           * submission is rejected due to an invalid `<file-input>`.  
           * 
           * @attributes invalidText
           * @type string
           * @default "No valid files selected."
          
          /**
           * This is a validation attribute that allows you to filter out any
           * files that do not contain a specific extension.  The value of this 
           * attribute is a JSON array string, containing all extensions to keep.  
           * You can also negate your extension array by including a `!` sign 
           * just before the array's opening bracket.
           * 
           * For example, to only accept "jpeg" files:
           * 
           *     <file-input extensions='["jpeg", "jpg"]'>
           *         Select Files
           *     </file-input>
           * 
           * To allow any extension EXCEPT "jpeg" files:
           * 
           *     <file-input extensions='!["jpeg", "jpg"]'>
           *         Select Files
           *     </file-input>
           * 
           * @attribute extensions
           * @type Array
           */
           
           /**
            * If you'd like to limit the number of files to accept from your 
            * users, specify this as an integer value for the `maxFiles` attribute.
            * 
            * For example, to only accept 3 files:
            * 
            *     <file-input maxFiles="3">
            *         Select Files
            *     </file-input>
            * 
            * If you'd like to completely prevent users from selecting more 
            * than one file from the file chooser, you can simply set 
            * `maxFiles` to 1:
            * 
            *     <file-input maxFiles="1">
            *         Select Files
            *     </file-input>
            *
            * @attribute maxFiles
            * @type integer
            * @default 0
            */
            
            /**
             * You can also specify maximum and minimum acceptable file sizes 
             * for the purposes of validation.  The values of each attribute 
             * are expected to be in bytes.
             * 
             * For example, to only allow files that are 1000 bytes or greater 
             * but not greater than 3000 bytes:
             * 
             *     <file-input minSize="1000" maxSize="3000">
             *         Select Files
             *     </file-input>
             * 
             * @attribute maxSize & minSize
             * @type integer
             * @default 0
             */
             
            /**
            * Include this attribute if this element is embedded in an `<ajax-form>`
            * and you want to prevent submission unless at least one valid file
            * has been selected.
            * 
            *     <file-input required>
            *         Select Files
            *     </file-input>
            *
            * @attribute required
            */

        Polymer('file-input', fileInput);
        
    </script>
    
</polymer-element>