Merge pull request #353 from goto-bus-stop/docs/uploaders

Add docs for XHRUpload, Tus

website/src/docs/aws-s3.md

@@ -1,6 +1,6 @@
 ---
 type: docs
-order: 10
+order: 32
 title: "AwsS3"
 permalink: docs/aws-s3/
 ---

website/src/docs/dashboard.md

@@ -1,6 +1,6 @@
 ---
 type: docs
-order: 6
+order: 20
 title: "Dashboard"
 permalink: docs/dashboard/
 ---

website/src/docs/dragdrop.md

@@ -1,6 +1,6 @@
 ---
 type: docs
-order: 7
+order: 21
 title: "DragDrop"
 permalink: docs/dragdrop/
 ---

website/src/docs/golder-retriever.md

@@ -2,7 +2,7 @@
 title: "Golden Retriever"
 type: docs
 permalink: docs/golden-retriever/
-order: 15
+order: 40
 ---
 
 Golden Retriever plugin saves selected files in your browser cache (Local Storage for metadata, then Service Worker for all blobs + IndexedDB for small blobs), so that if the browser crashes, Uppy can restore everything and continue uploading like nothing happened. Read more about it [on the blog](https://uppy.io/blog/2017/07/golden-retriever/).
@@ -42,4 +42,4 @@ if ('serviceWorker' in navigator) {
       console.log('Registration failed with ' + error)
     })
 }
-```
+```

website/src/docs/plugins.md

@@ -2,7 +2,7 @@
 title: "List & Common Options"
 type: docs
 permalink: docs/plugins/
-order: 4
+order: 10
 ---
 
 Plugins are what makes Uppy useful: they help select, manipulate and upload files.
@@ -116,7 +116,7 @@ Same as with Uppy.Core’s setting from above, this allows you to override plugi
 
 ```js
 .use(FileInput, {
-  target: 'body', 
+  target: 'body',
   locale: {
     strings: { selectToUpload: 'Выберите файл для загрузки' }
   }

website/src/docs/statusbar.md

@@ -1,6 +1,6 @@
 ---
 type: docs
-order: 8
+order: 22
 title: "StatusBar"
 permalink: docs/statusbar/
 ---

website/src/docs/transloadit.md

@@ -1,6 +1,6 @@
 ---
 type: docs
-order: 9
+order: 33
 title: "Transloadit"
 permalink: docs/transloadit/
 ---

website/src/docs/tus.md

@@ -1,19 +1,27 @@
 ---
-order: 7
-title: "Tus"
+type: docs
+order: 30
+title: "Tus10"
 permalink: docs/tus/
 ---
 
-Tus plugin brings [tus.io](http://tus.io) resumable file uploading to Uppy by wrapping the [tus-js-client](https://github.com/tus/tus-js-client).
-
-## Options
+The Tus10 plugin brings [tus.io](http://tus.io) resumable file uploading to Uppy by wrapping the [tus-js-client][].
 
 ```js
 uppy.use(Tus10, {
   resume: true,
-  allowPause: true,
   autoRetry: true,
   retryDelays: [0, 1000, 3000, 5000]
 })
 ```
 
+## Options
+
+The Tus10 plugin supports all of [tus-js-client][]'s options.
+Additionally:
+
+### `autoRetry: true`
+
+Whether to auto-retry the upload when the user's internet connection is back online after an outage.
+
+[tus-js-client]: https://github.com/tus/tus-js-client

website/src/docs/xhrupload.md

@@ -0,0 +1,103 @@
+---
+type: docs
+order: 31
+title: "XHRUpload"
+permalink: docs/xhrupload/
+---
+
+The XHRUpload plugin handles classic HTML multipart form uploads, as well as uploads using the HTTP `PUT` method.
+
+[Try it live](/examples/xhrupload/)
+
+```js
+uppy.use(XHRUpload, {
+  endpoint: 'http://my-website.org/upload'
+})
+```
+
+## Options
+
+### `endpoint: ''`
+
+URL to upload to.
+
+### `method: 'post'`
+
+HTTP method to use for the upload.
+
+### `formData: true`
+
+Whether to use a multipart form upload, using [FormData][].
+This works similarly to using a `<form>` element with an `<input type="file">` for uploads.
+When `true`, file metadata is also sent to the endpoint as separate form fields.
+When `false`, only the file contents are sent.
+
+### `fieldName: 'files[]'`
+
+When `formData` is true, this is used as the form field name for the file to be uploaded.
+
+### `metaFields: null`
+
+Pass an array of field names to limit the metadata fields that will be sent to the endpoint as form fields.
+For example, `metaFields: ['name']` will only send the `name` field.
+Passing `null` (the default) will send *all* metadata fields.
+
+If the `formData` option is false, `metaFields` has no effect.
+
+### `headers: {}`
+
+An object containing HTTP headers to use for the upload request.
+Keys are header names, values are header values.
+
+```js
+headers: {
+  'authorization': `Bearer ${window.getCurrentUserToken()}`
+}
+```
+
+### `getResponseData(xhr)`
+
+When an upload has completed, Uppy will extract response data from the upload endpoint and send it back in the `core:upload-success` event.
+By default, Uppy assumes the endpoint will return JSON. So, if `POST /upload` responds with:
+
+```json
+{
+  "url": "https://public.url/to/file",
+  "whatever": "beep boop"
+}
+```
+
+That object will be emitted in the `core:upload-success` event.
+
+Not all endpoints respond with JSON. Providing a `getResponseData` function overrides this behavior.
+The `xhr` parameter is the `XMLHttpRequest` instance used to upload the file.
+
+For example, an endpoint that responds with an XML document:
+
+```js
+getResponseData (xhr) {
+  return {
+    url: xhr.responseXML.querySelector('Location').textContent
+  }
+}
+```
+
+### `getResponseError(xhr)`
+
+If the upload endpoint responds with a non-2xx status code, the upload is assumed to have failed.
+The endpoint might have responded with some information about the error, though.
+Pass in a `getResponseError` function to extract error data from the `XMLHttpRequest` instance used for the upload.
+
+For example, if the endpoint responds with a JSON object containing a `{ message }` property, this would show that message to the user:
+
+```js
+getResponseError (xhr) {
+  return new Error(JSON.parse(xhr.response).message)
+}
+```
+
+### `responseUrlFieldName: 'url'`
+
+The field name containing a publically accessible location of the uploaded file in the response data returned by `getResponseData(xhr)`.
+
+[FormData]: https://developer.mozilla.org/en-US/docs/Web/API/FormData

website/src/examples/multipart/index.ejs → website/src/examples/xhrupload/index.ejs

@@ -3,6 +3,7 @@ title: XHRUpload (Multipart)
 layout: example
 type: examples
 order: 3
+alias: /examples/multipart/
 ---
 
 {% blockquote %}