Details | Last modification | View Log | RSS feed
| Rev | Author | Line No. | Line |
|---|---|---|---|
| 1 | espaco | 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). |