[REFACTOR] Rough Prototype

[stramel]

@jouni @marcus @platosha @admwx7 @haydenmcp @krumware

PTAL This is first attempt at making vaadin-upload more modular. All feedback is welcome.

A lot of files that are showing changed right now from working off an older commit and don't want to mess with rebasing yet. Best to start from vaadin-upload-ajax-uploader

Global TODOs:

• i18n
• JSDocs
• Unit Tests
• Configurability (Slots)
• Styling (Parts and CSS)
• Visual Regression Tests

---

vaadin-upload

Creates a 100% backwards compatible version of the existing vaadin-upload component but built from new components. This is an optional component that allows users to migrate to the new breaking syntax without having to update all instances.

TODO:

• Decide if this is worth keeping

---

vaadin-upload-ajax-uploader

Allows user to upload files using XHR. Fallsback to any specified uploader if not supported.

Mixes:

• UploaderMixin

Properties:

• url: Url to upload to
• method: (Optional, defaults to 'POST') Method to use for request
• params: (Optional, defaults to {}) Query params to send on request
• headers: (Optional, defaults to {}) Headers to apply to XHR on request
• timeout: (Optional, defaults to 0) Timeout for XHR request
• withCredentials: (Optional, defaults to false) True if request should be made with credentials
• formDataName: (Optional, defaults to 'file') Name of the form data item

Events:

• upload-preopen: Cancelable, Fired before xhr.open is called. Allows canceling the upload before XHR is opened
• upload-preflight: Cancelable, Fired before xhr.send is called. Allows canceling the upload before send or changing the send data.
• upload-start: Fired after the XHR upload has started.
• upload-response: Cancelable, Fired after XHR response comes back. Allows changing the response data.
• upload-error: Fired after a failed XHR.
• upload-success: Fired after a successful XHR.

TODO:

• Error status'
• Implement abort logic
• Implement getEventDetails logic
• Parallel Uploads (Move to Enhancement)

---

vaadin-upload-dropzone

Allows creating a dropzone to handle file drag and drop.

Properties:

• clickable: (Optional, defaults to false) Allows the dropzone area to be clickable for triggering the file dialog
• dropTarget: (Optional, defaults to self) Allows a user to specify different dropTargets: document, element id, element reference, or self.
• disabled: (Optional, defaults to false) Disables the dropzone from triggering any file additions.
• invalid: True if the files being dragged do not meet the specified criteria of the upload element
• active: True if the dropzone has files being dragged over it

Slots:

• upload: Takes the upload element which handles validation and addition of files
• DEFAULT: (Optional) Allows you to wrap contents with the dropzone.

TODO:

• Handle Validation
• Decide what to do with dragend (Not firing)
• Handle folders (Move to Enhancement, appears to be Chrome only)

---

vaadin-upload-fetch-uploader

TODO:

• Implement

---

vaadin-upload-file-list

Implements a virtual scroll list
NOTE: I'm not convinced we should implement this as it just wraps iron-list

Properties:

• files: Files to display

Slots:

• DEFAULT: Allows you to provide how the file should display

TODO:

• Decide if this should stay

---

vaadin-upload-file-uploader

TODO:

• Implement

---

vaadin-upload-file

Implements the default file item visualization

Properties:

• file: File to display

TODO:

• Solve actions
• Handle timing displays
• Handle errorMessage displays

---

vaadin-upload-icons

Adds the font icon data

---

vaadin-upload-image-preview

Implements a preview for images. Doesn't render non-images

Properties:

• file: Image to render
• alt: (Optional, defaults to file.name) Alt that should be associated with the image preview

TODO:

• Image resizing (Move to Enhancement)

---

vaadin-upload-localstorage-uploader

"Uploads" files to LocalStorage. Will fallback to any fallback uploader if LocalStorage is not supported. (Shouldn't ever not be supported on any modernish browser)
NOTE: Limited to amount of LocalStorage the browser has allocated for the site.

Mixes:

• UploaderMixin

Properties:

• path: (Optional, defaults to "files") Path to store the files at.

TODO:

• Handle subpaths, maybe? (ie. files.images) (Move to Enhancement)

---

vaadin-upload-mixin

Implements an interface for different upload components

Mixes:

• UtilsMixin

Properties:

• files: Notifies, List of files that have been added
• accept: (Optional) List of MIME Types or file extensions to accept
• capture: (Optional) Pass-through to input for capture type
• preventReload: (Optional, defaults to false) Prevents navigating away when uploads are in progress
• disabled: (Optional, defaults to false) Disables the input and button
• maxFileSize: (Optional, defaults to Infinity) Maximum file size to allow. Specified in unit of choice.
• unit: (Optional, defaults to kB) Unit to specify size in. (Useful for maxFileSize)
• invalid: Notify, Reflects, If true, the component is invalid.
• required: (Optional, defaults to false) Determines if this component should be able to fail validation.

Methods:

• openFileDialog: Allows user to trigger the open of the file dialog programmatically.
• remove: Allows user to remove a file
• addFiles: Allows user to add a file or multiple files that are not complete. Returns Array of Promises
• validate: Checks the validation state of the component. Component can override __getValidity(file) to implement the validation logic.
• validateFile: Checks the validation state of the file.

TODO:

• Merge validation
• Better way to handle event driven file operations
• Handle timings

---

vaadin-upload-multiple

Implements logic for allowing >= 1 files to be uploaded disabling the input and button after reaching max files. Also, keeps a list of the files uploaded.

Mixes:

• UploadMixin

Properties:

• minFiles: (Optional, defaults to 0) Minimum number of files that must be added to be considered valid.
• maxFiles: (Optional, defaults to Infinity) Maximum number of files that can be added.
• maxFilesReached: Notifies, ReadOnly, True if maxFiles was reached.

Slots:

• uploader: Uploader goes in here

---

vaadin-upload-single

Implements logic allowing for a single file to be uploaded and not disabling the input after the single upload. Does not keep a list of files that have been uploaded. Only handles the latest file

Mixes:

• UploadMixin

Slots:

• uploader: Uploader goes in here

TODO:

• Clear files on new file added

---

vaadin-upload-uploader-mixin

Implements the base logic for all uploaders.

Properties:

• fallback: (Optional) ReadOnly, If provided and the uploader isn't supported by the browser it will use this method instead.
• files: Notifies, The files to upload
• auto: (Optional, defaults to false) Upload immediately after adding
• retryOnError: (Optional, defaults to false) If true it will automatically re-attempt a failed upload.
• maxRetries: (Optional, defaults to 5) Limits number of retry attempts. Only applies if retryOnError is true.
• clearOnComplete (Optional, defaults to false) Removes the file upon completion. NOTE: Not sure if this is useful or better to have a method that can be called to clear on demand?

Methods:

• retry: Re-attempts to upload specified file. Returns a promise.
• abort: Kills a in progress file upload. Returns a promise.
• uploadFiles: Can take a single file or multiple to upload. Returns an Array of Promises.

Events:

• upload-before: Triggered before an actual upload process starts on a file.
• upload-abort: Triggered when abort is called on a file. NOTE: Not sure if this is necessary
• upload-retry: Triggered when retry is called on a file. NOTE: Not sure if this is necessary

TODO:

• Implement retryOnError with maxRetries
• Decide on if clearOnComplete is useful enough to implement
• Decide if abort and retry events are useful enough to keep
• Implement online/offline logic. Need advice on what to do in these cases. (Move to Enhancement)

---

vaadin-upload-file-item-mixin

---

vaadin-upload-video-preview

Implements logic to render a image preview of a video. Doesn't render if required features are not supported or not a video file.

Properties:

• file: The video file to render a image for.
• alt: (Optional, defaults to file.name) A string to use as the alt tag of the image preview.

TODO:

• Image resizing (Move to Enhancement)
• Maybe better detection of the video formats the browser will accept? (Move to Enhancement)

[krumware]

Looking good so far. Going to try to break it on legacy browsers tomorrow

[stramel]

NOTE: @jouni I'm having troubles getting String versions of headers to pass in like the old one handled.

[haydenmcp]

@stramel I noticed that the vaadin-upload-image-preview is provided. Is that based on a mixin or behavior that can be extended to perform preview for different file types?

[stramel]

@haydenmcp Unfortunately no, each type has to have custom implementation. Images, you read the file data and generate a preview. Videos you read the metadata and play first snippet, print to canvas, then export canvas to image data. Other file types don't really have a preview capability.

[haydenmcp]

@stramel That's too bad! Awesome job on this! I'm going to give it a second pass later but it's looking great!

[stramel]

Moved to vaadin#227