Merge pull request #1069 from transloadit/chore/document-events

[WIP] [@uppy/core] Document events, deprecate unused

packages/@uppy/core/src/index.js

@@ -514,7 +514,10 @@ class Uppy {
   }
 
   pauseResume (fileID) {
-    if (this.getFile(fileID).uploadComplete) return
+    if (!this.getState().capabilities.resumableUploads ||
+         this.getFile(fileID).uploadComplete) {
+      return
+    }
 
     const wasPaused = this.getFile(fileID).isPaused || false
     const isPaused = !wasPaused
@@ -860,14 +863,13 @@ class Uppy {
   /**
    * Find one Plugin by name.
    *
-   * @param {string} name description
+   * @param {string} id plugin id
    * @return {object | boolean}
    */
-  getPlugin (name) {
+  getPlugin (id) {
     let foundPlugin = null
     this.iteratePlugins((plugin) => {
-      const pluginName = plugin.id
-      if (pluginName === name) {
+      if (plugin.id === id) {
         foundPlugin = plugin
         return false
       }

packages/@uppy/dashboard/src/index.js

@@ -566,7 +566,6 @@ module.exports = class Dashboard extends Plugin {
     }
 
     const cancelUpload = (fileID) => {
-      this.uppy.emit('upload-cancel', fileID)
       this.uppy.removeFile(fileID)
     }
 

packages/@uppy/xhr-upload/src/index.js

@@ -288,13 +288,6 @@ module.exports = class XHRUpload extends Plugin {
         }
       })
 
-      this.uppy.on('upload-cancel', (fileID) => {
-        if (fileID === file.id) {
-          timer.done()
-          xhr.abort()
-        }
-      })
-
       this.uppy.on('cancel-all', () => {
         timer.done()
         xhr.abort()

website/src/docs/uppy.md

@@ -248,6 +248,14 @@ const uppy = Uppy()
 uppy.use(DragDrop, { target: 'body' })
 ```
 
+### `uppy.removePlugin(instance)`
+
+Uninstall and remove a plugin.
+
+### `uppy.getPlugin(id)`
+
+Get a plugin by its [`id`](/docs/plugins/#id) to access its methods.
+
 ### `uppy.getID()`
 
 Get the Uppy instance ID, see the [`id` option](#id-39-uppy-39).
@@ -332,6 +340,30 @@ uppy.upload().then((result) => {
 })
 ```
 
+### `uppy.pauseResume(fileID)`
+
+Toggle pause/resume on an upload. Will only work if resumable upload plugin, such as [Tus](/docs/tus/), is used.
+
+### `uppy.pauseAll()`
+
+Pause all uploads. Will only work if a resumable upload plugin, such as [Tus](/docs/tus/), is used.
+
+### `uppy.resumeAll()`
+
+Resume all uploads. Will only work if resumable upload plugin, such as [Tus](/docs/tus/), is used.
+
+### `uppy.retryUpload(fileID)`
+
+Retry an upload (after an error, for example).
+
+### `uppy.retryAll()`
+
+Retry all uploads (after an error, for example).
+
+### `uppy.cancelAll()`
+
+Cancel all uploads, reset progress and remove all files.
+
 ### `uppy.setState(patch)`
 
 Update Uppy's internal state. Usually, this method is called internally, but in some cases it might be useful to alter something directly, especially when implementing your own plugins.
@@ -391,6 +423,10 @@ Update the state for a single file. This is mostly useful for plugins that may w
 
 `fileID` is the string file ID. `state` is an object that will be merged into the file's state object.
 
+```js
+uppy.getPlugin('Url').addFile('path/to/remote-file.jpg')
+```
+
 ### `uppy.setMeta(data)`
 
 Alters global `meta` object in state, the one that can be set in Uppy options and gets merged with all newly added files. Calling `setMeta` will also merge newly added meta data with previously selected files.
@@ -552,6 +588,16 @@ uppy.on('upload-error', (file, error) => {
 })
 ```
 
+### `upload-retry`
+
+Fired when an upload has been retried (after an error, for example):
+
+```js
+uppy.on('upload-retry', (fileID) => {
+  console.log('upload retried:', fileID)
+})
+```
+
 ### `info-visible`
 
 Fired when “info” message should be visible in the UI. By default, `Informer` plugin is displaying these messages (enabled by default in `Dashboard` plugin). You can use this event to show messages in your custom UI:
@@ -572,3 +618,7 @@ uppy.on('info-visible', () => {
 ### `info-hidden`
 
 Fired when “info” message should be hidden in the UI. See [`info-visible`](#info-visible).
+
+### `cancel-all`
+
+Fired when [`uppy.cancelAll()`]() is called, all uploads are canceled, files removed and progress is reset.