redditor 0.1.0 → 0.1.1

data/app/assets/javascripts/redditor/fileapi/README.md

@@ -1,724 +0,0 @@
-# FileAPI — a set of tools for working with files.
-
-
-<p align="center">
- ~~~  <a href="http://mailru.github.com/FileAPI/">DEMO</a>
- ~~~  <a href="http://mailru.github.com/FileAPI/example.userpic.html">user pic</a>
- ~~~
-</p>
-
-
-## Support
- * Multiupload: all browsers that support HTML5 or [Flash](#flash-settings)
- * Drag'n'Drop upload: files (HTML5) & directories (Chrome 21+)
- * [Chunked](#chunked) file upload (HTML5)
- * Upload one file: all browsers
- * Working with [Images](#images): IE6+, FF 3.6+, Chrome 10+, Opera 11.1+, Safari 5.4+
-    + crop, resize, preview & rotate (HTML5 or Flash)
-    + auto orientation by exif (HTML5, if include FileAPI.exif.js or Flash)
-
-
-
-
-## Example
-```html
-<span class="js-fileapi-wrapper" style="position: relative;">
-	<input id="user-files" type="file" multiple />
-</span>
-
-<div id="preview-list">
-</div>
-```
-```js
-var input = document.getElementById('user-files');
-var previewNode = document.getElementById('preview-list');
-
-// Drag'n'Drop
-FileAPI.event.dnd(previewNode, function (over){
-	$(this).css('background', over ? 'red' : '');
-}, function (files){
-	// ..
-});
-
-
-
-FileAPI.event.on(input, 'change', function (evt){
-	var files = FileAPI.getFiles(evt.target); // or FileAPI.getFiles(evt)
-
-	// filtering
-	FileAPI.filterFiles(files, function (file, info){
-		if( /image/.test(file.type) && info ){
-			return	info.width >= 320 && info.height >= 240;
-		}
-		else {
-			return	file.size > 128;
-		}
-	}, function (fileList, ignor){
-		if( ignor.length ){
-			// ...
-		}
-
-		if( !fileList.length ){
-			// empty file list
-			return;
-		}
-
-
-		// do preview
-		var imageList = FileAPI.filter(fileList, function (file){ return /image/.test(file.type); });
-		FileAPI.each(imageList, function (imageFile){
-			FileAPI.Image(imageFile)
-				.preview(100, 120)
-				.get(function (err, image){
-					if( err ){
-						// ...
-					}
-					else {
-						previewNode.appendChild(image);
-					}
-				})
-			;
-		});
-
-
-		// upload on server
-		var xhr = FileAPI.upload({
-			url: '...',
-			data: { foo: 'bar' }, // POST-data (iframe, flash, html5)
-			headers: { 'x-header': '...' }, // request headers (html5)
-			files: {
-				files: FileAPI.filter(fileList, function (file){ return !/image/.test(file.type); }),
-				pictures: imageList
-			},
-			imageTransform: {
-				maxWidth:  1024,
-				maxHeight: 768
-			},
-			imageAutoOrientation: true,
-			fileprogress: function (evt){   // (flash, html5)
-				var percent = evt.loaded/evt.total*100;
-				// ...
-			},
-			progress: function (evt){    // (flash, html5)
-				var percent = evt.loaded/evt.total*100;
-				// ...
-			},
-			complete: function (err, xhr){
-				// ...
-			}
-		});
-	});
-});
-```
-
-### HTML structure (templates)
- * [Default](#html-default)
- * [Button](#html-button)
- * [Link](#html-link)
-
-
-### API
-* FileAPI.[getFiles](#getFiles)(`source:HTMLInput|Event`)`:Array`
-* FileAPI.[getDropFiles](#getDropFiles)(`files:Array`, `callback:Function`)
-* FileAPI.[filterFiles](#filterFiles)(`files:Array`, `iterator:Function`, `complete:Function`)
-* FileAPI.[upload](#upload)(`options:Object`)`:XMLHttpRequest`
-* FileAPI.[getInfo](#getInfo)(`file:File`, `callback:Function`)
-* FileAPI.[readAsImage](#readAs)(`file:File`, `callback:function`)
-* FileAPI.[readAsDataURL](#readAs)(`file:File`, `callback:function`)
-* FileAPI.[readAsBinaryString](#readAs)(`file:File`, `callback:function`)
-* FileAPI.[readAsArrayBuffer](#readAs)(`file:File`, `callback:function`)
-* FileAPI.[readAsText](#readAs)(`file:File`, `callback:function`)
-* FileAPI.[readAsText](#readAs)(`file:File`, `encoding:String`, `callback:function`)
-
-
-### Events
-* FileAPI.event.on(`el:HTMLElement`, `eventType:String`, `fn:Function`)
-* FileAPI.event.off(`el:HTMLElement`, `eventType:String`, `fn:Function`)
-* FileAPI.event.one(`el:HTMLElement`, `eventType:String`, `fn:Function`)
-* FileAPI.event.dnd(`el:HTMLElement`, `onHover:Function`, `onDrop:Function`)
-* jQuery('#el').dnd(onHover, onDrop)
-
-
-<a name="images"></a>
-### FileAPI.Image
-* .crop(width[, height])
-* .crop(x, y, width[, height])
-* .resize(width[, height])
-* .resize(width, height, `type:Enum(min,max,preview)`)
-* .preview(width[, height])
-* .rotate(deg)
-* .get(`fn:Function`)
-
-
-
-### Utils
-* FileAPI.KB
-* FileAPI.MB
-* FileAPI.GB
-* FileAPI.TB
-* FileAPI.support.`html5:Boolean`
-* FileAPI.support.`cors:Boolean`
-* FileAPI.support.`dnd:Boolean`
-* FileAPI.support.`flash:Boolean`
-* FileAPI.support.`canvas:Boolean`
-* FileAPI.support.`dataURI:Boolean`
-* FileAPI.support.`chunked:Boolean`
-* FileAPI.each(`obj:Object|Array`, `fn:function`, `context:Mixed`)
-* FileAPI.extend(`dst:Object`, `src:Object`)`:Object`
-* FileAPI.filter(`list:Array`, `iterator:Function`)`:Array`
-* FileAPI.isFile(`file:Mixed`)`:Boolean`
-* FileAPI.toBinaryString(`str:Base64`)`:String`
-
-
-
----------------------------------------
-
-
-<a name="getFiles"></a>
-### FileAPI.getFiles
-```js
-FileAPI.event.on('#my-file-1', 'change', onSelect);
-
-// or jQuery
-$('#my-file-2').on('change', onSelect);
-
-function onSelect(evt/**Event*/){
-	// (1) extract fileList from event
-	var files = FileAPI.getFiles(evt);
-
-	// (2) or so
-	var files = FileAPI.getFiles(evt.target);
-}
-```
-
-
-<a name="getDropFiles"></a>
-### FileAPI.getDropFiles
-```js
-function onDrop(evt){
-	FileAPI.getDropFiles(evt, function (files){
-		if( files.length ){
-			// ...
-		}
-	});
-}
-
-// OR
-
-var el = document.getElementById('el');
-FileAPI.event.dnd(el, function (over/**Boolean*/, evt/**Event*/){
-	el.style.background = over ? 'red' : '';
-}, function (files/**Array*/, evt/**Event*/){
-	// ...
-});
-```
-
-
-<a name="getInfo"></a>
-### FileAPI.getInfo
-```js
-FileAPI.getInfo(imageFile/**File*/, function (err/**Boolean*/, info/**Object*/){
-	if( !err ){
-		switch( info.exif.Orientation ){
-			// ...
-		}
-	}
-});
-
-// ...
-
-FileAPI.addInfoReader(/^image/, function (file/**File*/, callback/**Function*/){
-	// http://www.nihilogic.dk/labs/exif/exif.js
-	// http://www.nihilogic.dk/labs/binaryajax/binaryajax.js
-	FileAPI.readAsBinaryString(file, function (evt){
-		if( evt.type == 'load' ){
-			var binaryString = evt.result;
-			var oFile = new BinaryFile(binaryString, 0, file.size);
-			var exif  = EXIF.readFromBinaryFile(oFile);
-			callback(false, { 'exif': exif || {} });
-		}
-		else if( evt.type == 'error' ){
-			callback('read_as_binary_string');
-		}
-		else if( evt.type == 'progress' ){
-			// ...
-		}
-	});
-});
-```
-
-
-<a name="filterFiles"></a>
-### FileAPI.filterFiles
-```js
-FileAPI.filterFiles(files, function (file, info){
-	if( /image/.test(file.type) && info ){
-		return	info.width > 320 && info.height > 240;
-	}
-	return	file.size < 10 * FileAPI.MB;
-}, function (result, ignor){
-	// ...
-});
-```
-
-
-<a name="readAs"></a>
-### FileAPI.readAsImage, FileAPI.readAsDataURL (FileAPI.readAsBinaryString)
-```js
-FileAPI.readAsImage(file, function (evt){
-	if( evt.type == 'load' ){
-		var images = document.getElementById('images');
-		images.appendChild(evt.result);
-	}
-	else {
-		// ...
-	}
-});
-
-
-FileAPI.readAsDataURL(file, function (evt){
-	if( evt.type == 'load' ){
-		// success
-		var result = evt.result;
-	}
-	else if( evt.type == 'progress' ){
-		var pr = evt.loaded/evt.total * 100;
-	}
-	else {
-		// error
-	}
-});
-```
-
-
-<a name="upload"></a>
-### FileAPI.upload
-```js
-var xhr = FileAPI.upload({
-	url: '...',
-	data: { foo: 'bar' },
-	headers: { 'x-header': '...' },
-	files: {
-		images: FileAPI.filter(files, function (file){ return /image/.test(file.type); }),
-		customFile: { file: 'generate.txt', blob: customFileBlob }
-	},
-
-	chunkSize: 0, // or chunk size in bytes, eg: FileAPI.MB*.5 (html5)
-	chunkUploadRetry: 0, // number of retries during upload chunks (html5)
-
-	imageTransform: {
-		maxWidth: 1024,
-		maxHeight: 768
-	},
-	imageAutoOrientation: true,
-	prepare: function (file, options){
-		// prepare options for current file
-		options.data.filename = file.name;
-	},
-	upload: function (xhr, options){
-		// start uploading
-	},
-	fileupload: function (xhr, options){
-		// start file uploading
-	},
-	fileprogress: function (evt){
-		// progress file uploading
-		var filePercent = evt.loaded/evt.total*100;
-	},
-	filecomplete: function (err, xhr){
-		if( !err ){
-			var response = xhr.responseText;
-		}
-	},
-	progress: function (evt){
-		// total progress uploading
-		var totalPercent = evt.loaded/evt.total*100;
-	},
-	complete: function (err, xhr){
-		if( !err ){
-			// Congratulations, the uploading was successful!
-		}
-	}
-});
-```
-
-
-<a href="imageTransform"></a>
-### imageTransform
- * width`:Number`
- * height`:Number`
- * preview`:Boolean`
- * maxWidth`:Number`
- * maxHeight`:Number`
- * rotate`:Number`
-```js
-FileAPI.upload({
-	// ..
-	imageOriginal: false, // don't send original on server
-
-	imageTransform: {
-		// (1) Resize to 120x200
-		resize: { width: 120, height: 200 }
-
-		// (2) create preview 320x240
-		thumb:  { width: 320, height: 240, preview: true }
-
-		// (3) Resize by max side
-		max:    { maxWidth: 800, maxHeight: 600 }
-
-		// (4) Custom resize
-		custom: function (info, transform){
-			return transform
-					.crop(100, 100, 300, 200)
-					.resize(100, 50)
-				;
-		}
-	}
-});
-```
-
-
-<a name="imageAutoOrientation"></a>
-### imageAutoOrientation
-```js
-// (1) all images
-FileAPI.upload({
- 	// ..
-	imageAutoOrientation: true
-});
-
-// (2) or so
-FileAPI.upload({
-	// ..
-	imageAutoOrientation: true,
-	imageTransform: { width: .., height: .. }
-});
-
-// (3) or so
-FileAPI.upload({
-	// ..
-	imageTransform: { rotate: 'auto' }
-});
-
-// (4) only "800x600", original not modified
-FileAPI.upload({
-	// ..
-	imageTransform: {
-		"800x600": { width: 800, height: 600, rotate: 'auto' }
-	}
-});
-```
-
-
------
-
-
-<a name="flash-settings"></a>
-### Flash settings
-```html
-	<script>
-		var FileAPI = {
-			// @required
-			  staticPath: '/js/' // @default: "./"
-
-			// @optional
-			, flashUrl: '/js/FileAPI.flash.swf' // @default: FileAPI.staticPath + "FileAPI.flash.swf"
-			, flashImageUrl: '/js/FileAPI.flash.image.swf' // @default: FileAPI.staticPath + "FileAPI.flash.image.swf"
-		};
-	</script>
-	<script src="/js/FileAPI.min.js"></script>
-```
-
-#### Flash-request ([FileReference](http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/net/FileReference.html))
-The following sample HTTP POST request is sent from Flash Player to a server-side script if no parameters are specified:
-```
-  POST /handler.cfm HTTP/1.1
-  Accept: text/*
-  Content-Type: multipart/form-data;
-  boundary=----------Ij5ae0ae0KM7GI3KM7
-  User-Agent: Shockwave Flash
-  Host: www.example.com
-  Content-Length: 421
-  Connection: Keep-Alive
-  Cache-Control: no-cache
-
-  ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
-  Content-Disposition: form-data; name="Filename"
-
-  MyFile.jpg
-  ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
-  Content-Disposition: form-data; name="Filedata"; filename="MyFile.jpg"
-  Content-Type: application/octet-stream
-
-  FileDataHere
-  ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
-  Content-Disposition: form-data; name="Upload"
-
-  Submit Query
-  ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7--
-```
-
-
-
------
-
-
-
-<a name="chunked"></a>
-### Chunked file upload (html5)
-```js
-FileAPI.upload({
-	  url: '...'
-	, files: fileList
-	, chunkSize: .5 * FileAPI.MB // 512KB
-	, chunkUploadRetry: 1
-	, complete: function (err, xhr){}
-});
-```
-
-Client and server communicate to each other using the following HTTP headers and status codes.
-
-Client explicitly sets the following headers:
-* [Content-Range](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.16): bytes \<start-offset\>-\<end-offset\>/\<total\>
-* [Content-Disposition](http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1): attachment; filename=\<file-name\>
-
-Any other headers are set by a target browser and are not used by client.
-Library does not provide any facilities to track a file uniqueness across requests, it's left on developer's consideration.
-
-Client recognizes the following response codes:
-* 200, 201 - chunk is successfully saved
-* 416, 500 - recoverable error, library tries to resend chunk 'chunkUploadRetry' times then fails
-
-All the other codes - fatal error, user's involvement is recommend.
-
-
------
-
-
-
-### File object (https://developer.mozilla.org/en/DOM/File)
-```js
-{
-	name: 'fileName',
-	type: 'mime-type',
-	size: 'fileSize'
-}
-```
-
-
-### XMLHttpRequest
-```js
-{
-	status: Number,
-	statusText: Number,
-	readyState: Number,
-	response: Blob,
-	responseXML: XML,
-	responseText: String,
-	responseBody: String,
-	getResponseHeader: function (name/**String*/)/**String*/{},
-	getAllResponseHeaders: function ()/**Object*/{},
-	abort: function (){}
-}
-```
-
-
-### Cross-Domain upload-controller headers
-```php
-<?
-	header('Access-Control-Allow-Methods: POST, OPTIONS');
-	header('Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Range, Content-Disposition, Content-Type'); // and other custom headers
-	header('Access-Control-Allow-Origin: ' . $_SERVER['HTTP_ORIGIN']); // a comma-separated list of domains
-
-	if( $_SERVER['REQUEST_METHOD'] == 'OPTIONS' ){
-		exit;
-	}
-
-	if( $_SERVER['REQUEST_METHOD'] == 'POST' ){
-		// ...
-	}
-?>
-```
-
-
-### iframe
-#### POST-query
-```
-/controller.php
-	?foo=bar
-	&images=...
-	&callback=...
-```
-
-
-#### POST-response
-```php
-<script type="text/javascript">
-(function (ctx, jsonp){
-	if( ctx && ctx[jsonp] ){
-		ctx[jsonp](<?=$statusCode/*200 — OK*/?>, "<?=addslashes($statusText)?>", "<?=addslashes($response)?>");
-	}
-})(this.parent, "<?=htmlspecialchars($_POST['callback'])?>");
-</script>
-```
-
-
-
----
-
-
-
-### HTML structure (templates)
-
-<a name="html-default"></a>
-### Default
-```html
-<span class="js-fileapi-wrapper" style="position: relative; display: inline-block;">
-	<input name="files" type="file" multiple />
-</span>
-```
-
-
-<a name="html-button"></a>
-### Button
-```html
-<style>
-.upload-btn {
-	width: 130px;
-	height: 25px;
-	overflow: hidden;
-	position: relative;
-	border: 3px solid #06c;
-	border-radius: 5px;
-	background: #0cf;
-
-}
-	.upload-btn:hover {
-		background: #09f;
-	}
-	.upload-btn__txt {
-		z-index: 1;
-		position: relative;
-		color: #fff;
-		font-size: 18px;
-		font-family: "Helvetica Neue";
-		line-height: 24px;
-		text-align: center;
-		text-shadow: 0 1px 1px #000;
-	}
-	.upload-btn__inp {
-	 	top: -10px;
-		right: -40px;
-		z-index: 2;
-		position: absolute;
-		cursor: pointer;
-		opacity: 0;
-		filter: alpha(opacity=0);
-		font-size: 50px;
-	}
-</style>
-<div class="upload-btn js-fileapi-wrapper">
-	<div class="upload-btn__txt">Upload files</div>
-	<input class="upload-btn__inp" name="files" type="file" multiple />
-</div>
-```
-
-
-<a name="html-link"></a>
-### Link
-```html
-<style>
-.upload-link {
-	color: #36c;
-	display: inline-block;
-	*zoom: 1;
-	*display: inline;
-	overflow: hidden;
-	position: relative;
-	padding-bottom: 2px;
-	text-decoration: none;
-}
-	.upload-link__txt {
-		z-index: 1;
-		position: relative;
-		border-bottom: 1px dotted #36c;
-	}
-		.upload-link:hover .upload-link__txt {
-			color: #f00;
-			border-bottom-color: #f00;
-		}
-
-	.upload-link__inp {
-		top: -10px;
-		right: -40px;
-		z-index: 2;
-		position: absolute;
-		cursor: pointer;
-		opacity: 0;
-		filter: alpha(opacity=0);
-		font-size: 50px;
-	}
-</style>
-<a class="upload-link js-fileapi-wrapper">
-	<span class="upload-link__txt">Upload photo</span>
-	<input class="upload-link__inp" name="photo" type="file" accept=".jpg,.jpeg,.gif" />
-</a>
-```
-
-
----
-
-
-## Changelog
-### 1.2.5
- * [#86](https://github.com/mailru/FileAPI/issues/86): Smarter upload recovery
- * [#87](https://github.com/mailru/FileAPI/issues/87): Fixed upload files into browsers that do not support FormData
- * Fixed support "accept" attribute for Flash.
- * Fixed detection of HTML5 support for FireFox 3.6
- * + FileAPI.html5 option, default "true"
-
-
-### 1.2.4
- * Fixed auto orientation image by EXIF (Flash)
- * Fixed image dimensions after rotate (Flash)
- * [#82](https://github.com/mailru/FileAPI/issues/82): "undefined" data-fields cause exceptions
- * [#83](https://github.com/mailru/FileAPI/issues/83): Allow requests without files
- * [#84](https://github.com/mailru/FileAPI/pull/84): Fixed connection abort when waiting for connection recovery
-
-
-### 1.2.3
- * [#77](https://github.com/mailru/FileAPI/pull/77): Fixed flash.abort(), [#75](https://github.com/mailru/FileAPI/issues/75)
- * - `FileAPI.addMime`
- * + `FileAPI.accept` — fallback for flash.
-
-
-### 1.2.2
- * [#67](https://github.com/mailru/FileAPI/pull/67): Added correct httpStatus for upload fail, [#62](https://github.com/mailru/FileAPI/pull/68)
- * [#68](https://github.com/mailru/FileAPI/pull/68) Added "Content-Type" for chunked upload, [#65](https://github.com/mailru/FileAPI/pull/65)
- * [#69](https://github.com/mailru/FileAPI/issues/69): Fixed network down recovery
- * Fixed progress event, [#66](https://github.com/mailru/FileAPI/issues/66)
- * Increase flash stage size, [#73](https://github.com/mailru/FileAPI/pull/73)
- * - array index from POST-param "name", [#72](https://github.com/mailru/FileAPI/issues/72)
- * - dependency on FileAPI.Image for FileAPI.Flash
-
-
-### 1.2.1
- * [#64](https://github.com/mailru/FileAPI/issues/64): Bufixed for [#63](https://github.com/mailru/FileAPI/issues/63)
-
-
-
-### 1.2.0
- * [#57](https://github.com/mailru/FileAPI/issues/57): Chunked file upload
-
-
-### 1.1.0
- * [#54](https://github.com/mailru/FileAPI/issues/54): added `FileAPI.flashUrl` and `FileAPI.flashImageUrl`
-
-
-### 1.0.1
- * [#51](https://github.com/mailru/FileAPI/issues/51): remove circular references from `file-objects` (Flash transport)
- * added `changelog`
-
-
-### 1.0.0
- * first release