1
|
# Plupload
|
2
|
|
3
|
Plupload is a cross-browser multi-runtime file uploading API. Basically, a set of tools that will help you to
|
4
|
build a reliable and visually appealing file uploader in minutes.
|
5
|
|
6
|
Historically, Plupload comes from a dark and hostile age of no HTML5, hence all the alternative fallbacks,
|
7
|
like Flash, Silverlight and Java (still in development). It is meant to provide an API, that
|
8
|
will work anywhere and in any case, in one way or another. While having very solid fallbacks, Plupload
|
9
|
is built with the future of HTML5 in mind.
|
10
|
|
11
|
### Table of Contents
|
12
|
* [Backstory](https://github.com/moxiecode/plupload/blob/master/readme.md#backstory)
|
13
|
* [Structure](https://github.com/moxiecode/plupload/blob/master/readme.md#structure)
|
14
|
* [File API and XHR L2 pollyfills](https://github.com/moxiecode/moxie/blob/master/README.md)
|
15
|
* [Plupload API](https://github.com/moxiecode/plupload/wiki/API)
|
16
|
* [UI Widget](https://github.com/moxiecode/plupload/wiki/UI.Plupload)
|
17
|
* [Queue Widget](https://github.com/moxiecode/plupload/wiki/pluploadQueue)
|
18
|
* [Demos](https://github.com/jayarjo/plupload-demos/blob/master/README.md)
|
19
|
* [Building Instructions](https://github.com/moxiecode/plupload/blob/master/readme.md#build)
|
20
|
* [Getting Started](https://github.com/moxiecode/plupload/wiki/Getting-Started)
|
21
|
* [Options](https://github.com/moxiecode/plupload/wiki/Options)
|
22
|
* [Events](https://github.com/moxiecode/plupload/wiki/Uploader#wiki-events)
|
23
|
* [Methods](https://github.com/moxiecode/plupload/wiki/Uploader#wiki-methods)
|
24
|
* [Plupload in Your Language](https://github.com/moxiecode/plupload/wiki/Plupload-in-Your-Language)
|
25
|
* [File Filters](https://github.com/moxiecode/plupload/wiki/File-Filters)
|
26
|
* [Image Resizing on Client-Side](https://github.com/moxiecode/plupload/wiki/Image-Resizing-on-Client-Side)
|
27
|
* [Chunking](https://github.com/moxiecode/plupload/wiki/Chunking)
|
28
|
* [Upload to Amazon S3](https://github.com/moxiecode/plupload/wiki/Upload-to-Amazon-S3)
|
29
|
* [FAQ](https://github.com/moxiecode/plupload/wiki/Frequently-Asked-Questions)
|
30
|
* [Support](https://github.com/moxiecode/plupload/blob/master/readme.md##support)
|
31
|
* [Create a Fiddle](https://github.com/moxiecode/plupload/wiki/Create-a-Fiddle)
|
32
|
* [Contributing](https://github.com/moxiecode/plupload/blob/master/readme.md#contribute)
|
33
|
* [License](https://github.com/moxiecode/plupload/blob/master/readme.md#license)
|
34
|
* [Contact Us](http://www.moxiecode.com/contact.php)
|
35
|
|
36
|
<a name="backstory" />
|
37
|
### Backstory
|
38
|
|
39
|
Plupload started in a time when uploading a file in a responsive and customizable manner was a real pain.
|
40
|
Internally, browsers only had the `input[type="file"]` element. It was ugly and clunky at the same time.
|
41
|
One couldn't even change it's visuals, without hiding it and coding another one on top of it from scratch.
|
42
|
And then there was no progress indication for the upload process... Sounds pretty crazy today.
|
43
|
|
44
|
It was very logical for developers to look for alternatives and writing their own implementations, using
|
45
|
Flash and Java, in order to somehow extend limited browser capabilities. And so did we, in our search for
|
46
|
a reliable and flexible file uploader for
|
47
|
our [TinyMCE](http://www.tinymce.com/index.php)'s
|
48
|
[MCImageManager](http://www.tinymce.com/enterprise/mcimagemanager.php).
|
49
|
|
50
|
Quickly enough though, Plupload grew big. It easily split into a standalone project.
|
51
|
With major *version 2.0* it underwent another huge reconstruction, basically
|
52
|
[from the ground up](http://blog.moxiecode.com/2012/11/28/first-public-beta-plupload-2/),
|
53
|
as all the low-level runtime logic has been extracted into separate [File API](http://www.w3.org/TR/FileAPI/)
|
54
|
and [XHR L2](http://www.w3.org/TR/XMLHttpRequest/) pollyfills (currently known under combined name of [mOxie](https://github.com/moxiecode/moxie)),
|
55
|
giving Plupload a chance to evolve further.
|
56
|
|
57
|
<a name="structure" />
|
58
|
### Structure
|
59
|
|
60
|
Currently, Plupload may be considered as consisting of three parts: low-level pollyfills,
|
61
|
Plupload API and Widgets (UI and Queue). Initially, Widgets were meant only to serve as examples
|
62
|
of the API, but quickly formed into fully-functional API implementations that now come bundled with
|
63
|
the Plupload API. This has been a source for multiple misconceptions about the API as Widgets were
|
64
|
easily mistaken for the Plupload itself. They are only implementations, such as any of you can
|
65
|
build by yourself out of the API.
|
66
|
|
67
|
* [Low-level pollyfills (mOxie)](https://github.com/moxiecode/moxie) - have their own [code base](https://github.com/moxiecode/moxie) and [documentation](https://github.com/moxiecode/moxie/wiki) on GitHub.
|
68
|
* [Plupload API](https://github.com/moxiecode/plupload/wiki/API)
|
69
|
* [UI Widget](https://github.com/moxiecode/plupload/wiki/UI.Plupload)
|
70
|
* [Queue Widget](https://github.com/moxiecode/plupload/wiki/pluploadQueue)
|
71
|
|
72
|
<a name="build" />
|
73
|
### Building instructions
|
74
|
|
75
|
Plupload depends on File API and XHR2 L2 pollyfills that currently have their
|
76
|
[own repository](https://github.com/moxiecode/moxie) on GitHub. However, in most cases you shouldn't
|
77
|
care as we bundle the latest build of mOxie, including full and minified JavaScript source and
|
78
|
pre-compiled `SWF` and `XAP` components, with [every release](https://github.com/moxiecode/plupload/releases). You can find everything you may need under `js/` folder.
|
79
|
|
80
|
There are cases where you might need a custom build, for example free of unnecessary runtimes, half the
|
81
|
original size, etc. The difficult part of this task comes from mOxie and its set of additional runtimes
|
82
|
that require special tools on your workstation in order to compile.
|
83
|
Consider [build instructions for mOxie](https://github.com/moxiecode/moxie#build-instructions) -
|
84
|
everything applies to Plupload as well.
|
85
|
|
86
|
First of all, if you want to build custom Plupload packages you will require [Node.js](http://nodejs.org/),
|
87
|
as this is our build environment of choice. Node.js binaries (as well as Source)
|
88
|
[are available](http://nodejs.org/download/) for all major operating systems.
|
89
|
|
90
|
Plupload includes _mOxie_ as a submodule, it also depends on some other repositories for building up it's dev
|
91
|
environment - to avoid necessity of downloading them one by one, we recommended you to simply clone Plupload
|
92
|
with [git](http://git-scm.com/) recursively (you will require git installed on your system for this operation
|
93
|
to succeed):
|
94
|
|
95
|
```
|
96
|
git clone --recursive https://github.com/moxiecode/plupload.git
|
97
|
```
|
98
|
|
99
|
And finalize the preparation stage with: `npm install` - this will install all additional modules, including those
|
100
|
required by dev and test environments. In case you would rather keep it minimal, add a `--production` flag.
|
101
|
|
102
|
*Note:* Currently, for an unknown reason, locally installed Node.js modules on Windows, may not be automatically
|
103
|
added to the system PATH. So, if `jake` commands below are not recognized you will need to add them manually:
|
104
|
|
105
|
```
|
106
|
set PATH=%PATH%;%CD%\node_modules\.bin\
|
107
|
```
|
108
|
|
109
|
<a name="support" />
|
110
|
### Support
|
111
|
|
112
|
We are actively standing behind the Plupload and now that we are done with major rewrites and refactoring,
|
113
|
the only real goal that we have ahead is making it as reliable and bulletproof as possible. We are open to
|
114
|
all the suggestions and feature requests. We ask you to file bug reports if you encounter any. We may not
|
115
|
react to them instantly, but we constantly bear them in my mind as we extend the code base.
|
116
|
|
117
|
In addition to dedicated support for those who dare to buy our OEM licenses, we got
|
118
|
[discussion boards](http://www.plupload.com/punbb/index.php), which is like an enormous FAQ,
|
119
|
covering every possible application case. Of course, you are welcome to file a bug report or feature request,
|
120
|
here on [GitHub](https://github.com/moxiecode/plupload/issues).
|
121
|
|
122
|
Sometimes it is easier to notice the problem when bug report is accompained by the actual code. Consider providing
|
123
|
[a Plupload fiddle](https://github.com/moxiecode/plupload/wiki/Create-a-Fiddle) for the troublesome code.
|
124
|
|
125
|
<a name="contribute" />
|
126
|
### Contributing
|
127
|
|
128
|
We are open to suggestions and code revisions, however there are some rules and limitations that you might
|
129
|
want to consider first.
|
130
|
|
131
|
* Code that you contribute will automatically be licensed under the LGPL, but will not be limited to LGPL.
|
132
|
* Although all contributors will get the credit for their work, copyright notices will be changed to [Moxiecode Systems AB](http://www.moxiecode.com/).
|
133
|
* Third party code will be reviewed, tested and possibly modified before being released.
|
134
|
|
135
|
These basic rules help us earn a living and ensure that code remains Open Source and compatible with LGPL license. All contributions will be added to the changelog and appear in every release and on the site.
|
136
|
|
137
|
An easy place to start is to [translate Plupload to your language](https://github.com/moxiecode/plupload/wiki/Plupload-in-Your-Language#contribute).
|
138
|
|
139
|
You can read more about how to contribute at: [http://www.plupload.com/contributing](http://www.plupload.com/contributing)
|
140
|
|
141
|
<a name="license" />
|
142
|
### License
|
143
|
|
144
|
Copyright 2013, [Moxiecode Systems AB](http://www.moxiecode.com/)
|
145
|
Released under [GPLv2 License](https://github.com/moxiecode/plupload/blob/master/license.txt).
|
146
|
|
147
|
We also provide [commercial license](http://www.plupload.com/commercial.php).
|