From d2e48d2547a81ad648d0db9f247682be59f9201e Mon Sep 17 00:00:00 2001 From: John Datserakis Date: Wed, 7 Oct 2020 22:40:22 -0400 Subject: [PATCH] Update readme --- README.md | 211 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 128 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index b6f04e3..ef7fb14 100644 --- a/README.md +++ b/README.md @@ -27,12 +27,13 @@ For the most part, browsers do a good job of handling image-uploads. That being **file-upload-with-preview** aims to address the issue of showing a preview of a user's uploaded image in a simple to use package. ### Features -- Shows the actual image preview in the case of a single uploaded .jpg, .jpeg, .gif, or .png image. Shows a *success-image* in the case of an uploaded .pdf file, uploaded video, or other unrenderable file - so the user knows their image was collected successfully. In the case of multiple selected files, the user's selected images will be shown in a grid. -- Shows the image name in the input bar. Shows the count of selected images in the case of multiple selections within the same input. -- Allows the user to clear their upload, and clear individual images in the `multiple` grid. -- Looks great - styling based on Bootstrap 4's [custom file-upload](https://getbootstrap.com/docs/4.0/components/forms/#file-browser) style. -- Framework agnostic - to access the uploaded file/files just use the `cachedFileArray` (always will be an array) property of your `FileUploadWithPreview` object. -- For every file-group you want just initialize another `FileUploadWithPreview` object with its own `uniqueId` - this way you can have multiple file-uploads on the same page. You also can just use a single input designated with a `multiple` property to allow multiple files on the same input. + +- Shows the actual image preview in the case of a single uploaded .jpg, .jpeg, .gif, or .png image. Shows a _success-image_ in the case of an uploaded .pdf file, uploaded video, or other unrenderable file - so the user knows their image was collected successfully. In the case of multiple selected files, the user's selected images will be shown in a grid. +- Shows the image name in the input bar. Shows the count of selected images in the case of multiple selections within the same input. +- Allows the user to clear their upload, and clear individual images in the `multiple` grid. +- Looks great - styling based on Bootstrap 4's [custom file-upload](https://getbootstrap.com/docs/4.0/components/forms/#file-browser) style. +- Framework agnostic - to access the uploaded file/files just use the `cachedFileArray` (always will be an array) property of your `FileUploadWithPreview` object. +- For every file-group you want just initialize another `FileUploadWithPreview` object with its own `uniqueId` - this way you can have multiple file-uploads on the same page. You also can just use a single input designated with a `multiple` property to allow multiple files on the same input. ### Installation @@ -43,10 +44,11 @@ npm i file-upload-with-preview # yarn yarn add file-upload-with-preview ``` + Or you can include it through the browser at the bottom of your page. When using the browser version make sure update your target version as needed. ```html - + ``` ### Usage @@ -55,19 +57,20 @@ When installed through npm or yarn: ```javascript // using require -const FileUploadWithPreview = require('file-upload-with-preview') +const FileUploadWithPreview = require("file-upload-with-preview"); // using import -import FileUploadWithPreview from 'file-upload-with-preview' +import FileUploadWithPreview from "file-upload-with-preview"; // initialize a new FileUploadWithPreview object -const upload = new FileUploadWithPreview('myUniqueUploadId') +const upload = new FileUploadWithPreview("myUniqueUploadId"); ``` + ...or through the browser: ```html ``` @@ -75,26 +78,45 @@ You'll also want to include the css: ```javascript // JavaScript -import 'file-upload-with-preview/dist/file-upload-with-preview.min.css' +import "file-upload-with-preview/dist/file-upload-with-preview.min.css"; ``` Or in your `` if you're in the browser: ```html - + ``` The JavaScript looks for a specific set of HTML elements to display the file input, label, image preview, and clear-button. Make sure to populate the `custom-file-container` element with the uniqueId: - ```html
- -
@@ -103,29 +125,29 @@ The JavaScript looks for a specific set of HTML elements to display the file inp Then when you're ready to use the user's file for an API call or whatever, just access the user's uploaded file/files in the `cachedFileArray` property of your initialized object like this: ```javascript -upload.cachedFileArray +upload.cachedFileArray; ``` You can optionally trigger image browser and clear selected images by script code: ```javascript -upload.emulateInputSelection() // to open image browser -upload.clearPreviewPanel() // clear all selected images +upload.emulateInputSelection(); // to open image browser +upload.clearPreviewPanel(); // clear all selected images ``` You may also want to capture the event when an image is selected: ```javascript -window.addEventListener('fileUploadWithPreview:imagesAdded', function(e) { +window.addEventListener("fileUploadWithPreview:imagesAdded", function (e) { // e.detail.uploadId // e.detail.cachedFileArray // e.detail.addedFilesCount // Use e.detail.uploadId to match up to your specific input - if (e.detail.uploadId === 'mySecondImage') { - console.log(e.detail.cachedFileArray) - console.log(e.detail.addedFilesCount) + if (e.detail.uploadId === "mySecondImage") { + console.log(e.detail.cachedFileArray); + console.log(e.detail.addedFilesCount); } -}) +}); ``` #### Note @@ -136,50 +158,49 @@ Make sure to set `multiple` on your input if you want to allow the user to selec ### Properties -| name | type | description | -|---|---|---| -| el | Element | The main container for the instance | -| input | Element | The main container for the instance | -| inputLabel | Element | The label for the image name/count | -| uploadId | String | The id you set for the instance | -| cachedFileArray | Array | The current selected files | -| currentFileCount | Number | The count of the currently selected files | -| clearButton | Element | The button to reset the instance | -| imagePreview | Element | The display panel for the images | -| options.images.baseImage | String | Replace placeholder image. | -| options.images.backgroundImage | String | Replace background image for image grid. | -| options.images.successFileAltImage | String | Replace successful alternate file upload image. | -| options.images.successPdfImage | String | Replace successful PDF upload image. | -| options.images.successVideoImage | String | Replace successful video upload image. | -| options.presetFiles | Array | Provide an array of image paths to be automatically uploaded and displayed on page load (can be images hosted on server or URLs) | -| options.showDeleteButtonOnImages | Boolean | Show a delete button on images in the grid. Default `true` | -| options.text.browse | String | Edit button text. Default `'Browse'`| -| options.text.chooseFile | String | Edit input placeholder text. Default `'Choose file...'`| -| options.text.selectedCount | String | Edit input text when multiple files have been selected in one input. Default `${ n } 'files selected'` | -| options.maxFileCount | Number | Set a maximum number of files you'd like the component to deal with. Must be `> 0` if set. By default there is no limit. | +| name | type | description | +| ---------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | +| el | Element | The main container for the instance | +| input | Element | The main container for the instance | +| inputLabel | Element | The label for the image name/count | +| uploadId | String | The id you set for the instance | +| cachedFileArray | Array | The current selected files | +| currentFileCount | Number | The count of the currently selected files | +| clearButton | Element | The button to reset the instance | +| imagePreview | Element | The display panel for the images | +| options.images.baseImage | String | Replace placeholder image. | +| options.images.backgroundImage | String | Replace background image for image grid. | +| options.images.successFileAltImage | String | Replace successful alternate file upload image. | +| options.images.successPdfImage | String | Replace successful PDF upload image. | +| options.images.successVideoImage | String | Replace successful video upload image. | +| options.presetFiles | Array | Provide an array of image paths to be automatically uploaded and displayed on page load (can be images hosted on server or URLs) | +| options.showDeleteButtonOnImages | Boolean | Show a delete button on images in the grid. Default `true` | +| options.text.browse | String | Edit button text. Default `'Browse'` | +| options.text.chooseFile | String | Edit input placeholder text. Default `'Choose file...'` | +| options.text.selectedCount | String | Edit input text when multiple files have been selected in one input. Default `${ n } 'files selected'` | +| options.maxFileCount | Number | Set a maximum number of files you'd like the component to deal with. Must be `> 0` if set. By default there is no limit. | ### Methods -| method | parameters | description | -|---|---|---| -| addFiles | array of File objects | Populate the `cachedFileArray` with images as File objects | -| processFile | file object | Take a single File object and append it to the image preview panel | -| addImagesFromPath | array of image paths | Take an array of image paths, convert them to File objects, and display them in the image preview panel (can be paths to images on the server or urls) | -| replaceFiles | array of File objects | Replace files in `cachedFileArray` and image preview panel with array of File objects | -| replaceFileAtIndex | file object, index (Number) | Take a single file object and index, replace existing file at that index | -| deleteFileAtIndex | index (Number) | Delete specified file from `cachedFileArray` | -| refreshPreviewPanel | none | Refresh image preview panel with current `cachedFileArray` | -| addBrowseButton | text | Appends browse button to input with custom button text | -| emulateInputSelection | none | Open the image browser programmatically | -| clearPreviewPanel | none | Clear the `cachedFileArray` | - +| method | parameters | description | +| --------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| addFiles | array of File objects | Populate the `cachedFileArray` with images as File objects | +| processFile | file object | Take a single File object and append it to the image preview panel | +| addImagesFromPath | array of image paths | Take an array of image paths, convert them to File objects, and display them in the image preview panel (can be paths to images on the server or urls) | +| replaceFiles | array of File objects | Replace files in `cachedFileArray` and image preview panel with array of File objects | +| replaceFileAtIndex | file object, index (Number) | Take a single file object and index, replace existing file at that index | +| deleteFileAtIndex | index (Number) | Delete specified file from `cachedFileArray` | +| refreshPreviewPanel | none | Refresh image preview panel with current `cachedFileArray` | +| addBrowseButton | text | Appends browse button to input with custom button text | +| emulateInputSelection | none | Open the image browser programmatically | +| clearPreviewPanel | none | Clear the `cachedFileArray` | ### Events -| event | value | description | -|---|---|---| -| fileUploadWithPreview:imagesAdded | `e` (e.detail.uploadId, e.detail.cachedFileArray, e.detail.addedFilesCount) | Triggered each time file/files are selected. Delivers the `uploadId`, updated `cachedFilesArray`, and `addedFilesCount` for the event. | -| fileUploadWithPreview:imageDeleted | `e` (e.detail.uploadId, e.detail.cachedFileArray, e.detail.currentFileCount) | Triggered each time a file is deleted. Delivers the `uploadId`, updated `cachedFilesArray`, and `currentFileCount` for the event. | +| event | value | description | +| ---------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| fileUploadWithPreview:imagesAdded | `e` (e.detail.uploadId, e.detail.cachedFileArray, e.detail.addedFilesCount) | Triggered each time file/files are selected. Delivers the `uploadId`, updated `cachedFilesArray`, and `addedFilesCount` for the event. | +| fileUploadWithPreview:imageDeleted | `e` (e.detail.uploadId, e.detail.cachedFileArray, e.detail.currentFileCount) | Triggered each time a file is deleted. Delivers the `uploadId`, updated `cachedFilesArray`, and `currentFileCount` for the event. | ### Full Example @@ -187,49 +208,67 @@ Make sure to set `multiple` on your input if you want to allow the user to selec ... - + ... - ...
- - -
... - + - ``` @@ -237,7 +276,12 @@ Make sure to set `multiple` on your input if you want to allow the user to selec In this example we set the `MAX_FILE_SIZE` value to `10485760` (10MB), the accepted images to `*` (everything), and designate `multiple` to allow the user to select multiple files - you can adjust those settings to whatever you like. For example, if you'd like to limit uploads to only images and pdf's and only allow a single file upload use the following: ```html - + ``` @@ -255,12 +299,13 @@ In this example we set the `MAX_FILE_SIZE` value to `10485760` (10MB), the accep ### Browser Support - If you are supporting a browser like IE11, you'll need a polyfill for `fetch` and `promise` at the bottom of your `index.html`: +If you are supporting a browser like IE11, you'll need a polyfill for `fetch` and `promise` at the bottom of your `index.html`: ```html ``` + Or, you can install babel-polyfill and import that in the main script of your app. You can read more about babel-polyfill [here](https://babeljs.io/docs/en/babel-polyfill). In the example folder, we use the external script method. ### Testing @@ -290,4 +335,4 @@ Go ahead and fork the project! Submit an issue if needed. Have fun! Copywrite 2017 [Promosis](https://promosis.com) -[MIT](http://opensource.org/licenses/MIT) \ No newline at end of file +[MIT](http://opensource.org/licenses/MIT)