|
|
@@ -2,75 +2,148 @@
|
|
|
type: api
|
|
|
order: 0
|
|
|
title: "Architecture"
|
|
|
-permalink: api/
|
|
|
+permalink: api/architecture
|
|
|
---
|
|
|
|
|
|
-*Work in progress, API not stable. Last update: 2015-12-03*
|
|
|
+Uppy has a lean [Core](https://github.com/transloadit/uppy/blob/master/src/core/Core.js) module and [Plugins](https://github.com/transloadit/uppy/tree/master/src/plugins) (see simple [Input](https://github.com/transloadit/uppy/blob/master/src/plugins/Formtag.js) as an example) that extend its functionality. Here’s how it’s currently used:
|
|
|
|
|
|
-### The Gist
|
|
|
+{% include_code lang:js ../api-usage-example.ejs %}
|
|
|
|
|
|
-``` javascript
|
|
|
-import Uppy from './src/core';
|
|
|
-import { DragDrop, Tus10 } from './src/plugins';
|
|
|
-
|
|
|
-const uppy = new Uppy({wait: false});
|
|
|
-const files = uppy
|
|
|
- .use(DragDrop, {selector: '#upload-target'})
|
|
|
- .use(Tus10, {endpoint: 'http://master.tus.io:8080'})
|
|
|
- .run();
|
|
|
-```
|
|
|
+## Core
|
|
|
+
|
|
|
+Core module orchestrates everything in Uppy. Plugins are added to it via `.use(Plugin, opts)` API, like `.use(DragDrop, {target: 'body'})`. Core instantiates plugins with `new Plugin(this, opts)`, passing options to them, then places them in `plugins` object, nested by type: `uploader`, `progressindicator`, `acquirer`, etc.
|
|
|
+
|
|
|
+Core then iterates over `plugins` object and calls `install` on each plugin. In its `install`
|
|
|
+method a plugin can extend global state with its state, set event listeners to react to events happening in Uppy (upload progress, file has been removed), or do anything else needed on init.
|
|
|
+
|
|
|
+Each time `state` is updated with `setState(stateAddition)`, Core runs `updateAll()` that re-renders all of the plugins (components) that have been mounted in the dom somewhere, using the new state.
|
|
|
+
|
|
|
+Core is very lean (at least should be), and acts as a glue that ties together all the plugins, shared data and functionality together. It keeps `state` with `files`, `capabilities`, plus exposes a few methods that are called by plugins to update state — adding files, adding preview Thumbnails to images, updating progress for each file and total progress, etc.
|
|
|
+
|
|
|
+*Comment: There is a discussion that these methods could in theory all live in Utils or be standalone modules used by plugins and the user directly, see https://github.com/transloadit/uppy/issues/116#issuecomment-247695921.*
|
|
|
+
|
|
|
+### getState()
|
|
|
+
|
|
|
+Returns current state.
|
|
|
+
|
|
|
+### setState({itemToUpdate: data})
|
|
|
+
|
|
|
+Updates state with new state (Object.assign({}, this.state, newState)) and then runs `updateAll()`.
|
|
|
+
|
|
|
+### updateAll()
|
|
|
+
|
|
|
+Iterates over all `plugins` and runs `update()` on each of them.
|
|
|
+
|
|
|
+### updateMeta(data, fileID)
|
|
|
+
|
|
|
+Given `{ size: 1200 }` adds that metadata to a file.
|
|
|
+
|
|
|
+### addFile(file)
|
|
|
+
|
|
|
+Adds a new file to `state`. This method is used by `acquirer` plugins like Drag & Drop, Webcam and Google Drive,
|
|
|
+or can be called by the user on uppy instance directly: `uppy.addFile(myFile)`.
|
|
|
+
|
|
|
+Normalizes that file too: tries to figure out file type by extension if mime is missing, use noname if name is missing, sets progress: 0 and so on.
|
|
|
+
|
|
|
+### removeFile(fileID)
|
|
|
+
|
|
|
+Removes file from `state.files`.
|
|
|
+
|
|
|
+### addThumbnail(fileID)
|
|
|
+
|
|
|
+Reads image from file’s data object in base64 and resizes that, using canvas. Then `state` is updated with a file that has thumbnail in it. Thumbnails are used for file previews by plugins like Dashboard.
|
|
|
+
|
|
|
+### state.capabilities
|
|
|
+
|
|
|
+Core (or plugins) check and set capabilities, like: `resumable: true` (this is set by Tus Plugin), `touch: false`, `dragdrop: true`, that could possibly be used by all plugins.
|
|
|
+
|
|
|
+### log(msg)
|
|
|
|
|
|
-### Core
|
|
|
+Logs stuff to console only if user specified `debug: true`, silent in production.
|
|
|
|
|
|
-1. Core class `Uppy` accepts object `options` (with general options), and exposes methods `.use` for adding plugins and `.set` for setting options.
|
|
|
-2. We create a new instance of `Uppy` and call `.use` on it, passing the plugins and their options.
|
|
|
-3. Then `run` is called to get things going.
|
|
|
-4. Plugins have types: `presetter`, `orchestrator`, `progressindicator`, `acquirer`, `uploader`, and `presenter` (more could be added in the future). When `use` is called, each plugin’s `run` method is added to an array of corresponding types, `methods`.
|
|
|
-5. Ok, now the tricky part. Core’s method `run` iterates over plugin types in a waterfall manner — each `runTypes` runs its `method`s in parallel and returns an array of results (files) to the next plugin type in the waterfall. This way we first get all the of files from `DragDrop`, `Dropbox`, `Instagram` and other inputs — then parse them somehow — and then upload:
|
|
|
+### core.on('event', action), core.emit('event')
|
|
|
|
|
|
-
|
|
|
+An event emitter embedded into Core that is passed to Plugins, and can be used directly on the instance. Used by Plugins for communicating with other Plugins and Core.
|
|
|
|
|
|
-### Plugins
|
|
|
+For example:
|
|
|
|
|
|
-1. Plugins are registered like this:
|
|
|
-```javascript
|
|
|
-uppy
|
|
|
- .use(DragDrop, {selector: '#upload-target'})
|
|
|
- .use(Tus10, {endpoint: 'http://master.tus.io:8080'})
|
|
|
+- Core listens for `core:upload-progress` event and calculates speed & ETA for all files currently in progress. *Uploader plugins could just call core.updateProgress().*
|
|
|
+- Core checks if browser in offline or online and emits `core:is-offline` or `core:is-online` that other plugins can listen to.
|
|
|
+- Any plugin can emit `informer` event that `Informer` plugin can use to display info bubbles. Currently only used in the Dashboard plugin. Example: `core.emitter.emit('informer', 'Connected!', 'success', 3000)`. *(Should this be a Core method instead of Plugin? Could be replaced by core.inform(info) method that will just update state with info)*
|
|
|
+- Uploader plugins listen to `core:upload` event (can be emitted after a file has been added or when upload button has been pressed), get files via `core.getState().files`, filter those that are not marked as complete and upload them, emitting progress events.
|
|
|
+
|
|
|
+*See discussion about Core and Event Emitter: https://github.com/transloadit/uppy/issues/116#issuecomment-247695921*
|
|
|
+
|
|
|
+## Plugins
|
|
|
+
|
|
|
+Plugins extend the functionality of Core (which itself is very much barebones, does almost nothing). Plugins actually do the work — select files, modify and upload them, and show the UI.
|
|
|
+
|
|
|
+Plugins that have some UI can be mounted anywhere in the dom. With current design you can have a Drag & Drop area in `#dragdrop` and Progressbar in `body`. Plugins can also be mounted into other plugins that support that, like Dashboard.
|
|
|
+
|
|
|
+Each plugin extends `Plugin` class with default methods that can be overridden:
|
|
|
+
|
|
|
+### update()
|
|
|
+
|
|
|
+Gets called when state changes and `updateAll()` is called from Core. Checks if a DOM element (tree) has been created with a reference for it stored in plugin’s `this.el`. If so, creates a new element (tree) `const newEl = this.render(currentState)` for current plugin and then calls `yo.update(this.el, newEl)` to effectively update the existing element to match the new one (morphdom is behind that).
|
|
|
+
|
|
|
+All together now:
|
|
|
+
|
|
|
+``` javascript
|
|
|
+const newEl = this.render(currentState)
|
|
|
+yo.update(this.el, newEl)
|
|
|
```
|
|
|
|
|
|
-Internally, plugins extend from a [`Plugin`](https://github.com/transloadit/uppy/blob/master/src/plugins/Plugin.js) class, see that for details.
|
|
|
+### mount(target, plugin)
|
|
|
|
|
|
+Called by the plugin itself, if it is a UI plugin that needs to do something in DOM. A `target` is passed as an argument. There are two possible scenarios for mounting:
|
|
|
|
|
|
-2. Settings and handlers are chainable, set like this:
|
|
|
-```javascript
|
|
|
-uppy
|
|
|
- .set({ wait: true })
|
|
|
- .use(Modal, {target: 'div#mycontainer', some: 'config'})
|
|
|
- .use(DragDrop, {target: Modal})
|
|
|
- .use(Instagram, {target: Modal, some: 'config'})
|
|
|
- .on('progress', handleProgress)
|
|
|
- .on('error', handleError);
|
|
|
+1\. If `typeof target === 'string'`, then the element (tree) is rendered and gets mounted to the DOM:
|
|
|
+
|
|
|
+``` javascript
|
|
|
+this.el = plugin.render(this.core.state)
|
|
|
+document.querySelector(target).appendChild(this.el)
|
|
|
```
|
|
|
|
|
|
-3. In `Uppy` everything is a plugin: a `Modal` dialog, `Drag & Drop`, `Instagram`. We borrow general approach from the new Babel and PostCSS — each chunk of functionality exists as separate plugin — easier to pick and choose exactly what you need to get a lightweight solution for production, while also easier to develop and avoid merge conflicts.
|
|
|
+2\. If `typeof target === 'object'`, then that plugin is found in `plugins` object of Core and `addTarget()` is called on that plugin.
|
|
|
|
|
|
-4. There will be a simplified preset that strings together many Plugins using sane defaults.
|
|
|
-```javascript
|
|
|
-uppy
|
|
|
- .use(Basic, {target: 'div#mycontainer', endpoint: 'http://master.tus.io:8080'})
|
|
|
- .run();
|
|
|
+``` javascript
|
|
|
+const targetPlugin = this.core.getPlugin(targetPluginName)
|
|
|
+const selectorTarget = targetPlugin.addTarget(plugin)
|
|
|
```
|
|
|
|
|
|
-5. Users will be able to roll out themes and style settings via plain CSS .
|
|
|
+### focus()
|
|
|
+
|
|
|
+Called when plugin is in focus, like when that plugin’s tab is selected in the Dashboard.
|
|
|
+
|
|
|
+### install()
|
|
|
+
|
|
|
+Called by Core when it instantiates new plugins. In `install`
|
|
|
+a plugin can extend global state with its own state (like `{ modal: { isHidden: true } }`), or do anything needed on initialization, including `mount()`.
|
|
|
+
|
|
|
+### Plugins are currently of the following types:
|
|
|
+
|
|
|
+### acquirer
|
|
|
+
|
|
|
+- **DragDrop** — simple DragDrop, once file is dropped on a target, it gets added to state.files. “click here to select” too
|
|
|
+- **GoogleDrive** — GoogleDrive UI, uses uppy-server component. Files are downloaded from Google Drive to uppy-server, without having to go through the client, saving bandwidth and space
|
|
|
+- **Formtag** — simple input[type=file] element
|
|
|
+- **Webcam** — allows to take pictures with your webcam, works in most browsers, except Safari. Flash (ugh) is used for fallback
|
|
|
+
|
|
|
+### orchestrator
|
|
|
+
|
|
|
+*Should probably be called UI*
|
|
|
+
|
|
|
+- **Dashboard** — the full-featured interface for interacting with Uppy. Supports drag & dropping files, provides UI for Google Drive, Webcam and any other plugin, shows selected files, shows progress on them.
|
|
|
+
|
|
|
+### progressindicator
|
|
|
+
|
|
|
+- **ProgressBar** — tiny progressbar that can be mounted anywhere.
|
|
|
+
|
|
|
+### uploader
|
|
|
|
|
|
-6. Would be cool if you could use whatever drag & drop library you wanted (DropZone) with our wrapper.
|
|
|
+- **Tus10** — tus resumable file uploads, see http://tus.io
|
|
|
+- **Multipart** — regular form/multipart/xhr uploads
|
|
|
|
|
|
-### References & Inspiration
|
|
|
+### modifier
|
|
|
|
|
|
-1. [PostCSS](https://github.com/postcss/postcss/blob/master/lib/postcss.es6#L19)
|
|
|
-2. [Markdown-It](https://github.com/markdown-it/markdown-it/blob/master/lib/index.js#L459)
|
|
|
-3. [Babel](babeljs.io)
|
|
|
-4. [Lodash](https://lodash.com/)
|
|
|
-5. [Vue.js](http://vuejs.org/guide/plugins.html#Using_a_Plugin)
|
|
|
-6. [The tus js client](https://github.com/tus/tus-js-client)
|
|
|
+- **Metadata** — allows adding custom metadata fields, data from each field is then added to a file
|
Artur Paikin