/README.md

 1S3Upload
 2========
 3
 4A jQuery plugin for direct upload to an Amazon S3 bucket. 
 5
 6It works by replacing a file input with a html element overlaid with a transparent SWF. The same way [Flickr](http://www.flickr.com/photos/upload/) does it. 
 7
 8By signing the request server side we also avoid the security issue of showing the Amazon AWS Access Id Key and Secure Key in plain text. A library for signing the request in Ruby is included, but the logic should be very easy to replicate in other languages like PHP or Python.
 9
10The Javascript API also allows these callback functions: 
11
12* onselect(info) 	- Called when a user has selected a file.
13* oncancel(info) 	- Called if the user decides to abort the file browsing.
14* onstart(info) 	- Called after the request has been signed and the file upload to S3 is starting.
15* onprogress(progress,info) - Called while uploading, "progress" being a float between 0 and 1 of the current upload progress.
16* oncomplete(info) 	- Called when the upload has finished successfully.
17* onerror(msg,info) - Called if there's been a problem with a message saying what failed.
18* onenabled()		- Called when the SWF has been enabled. Usually when swf.enable() has been called. Called first thing when the SWF is finished initializing.
19* ondisabled()		- Called when the SWF has been disabled. Usually when swf.disable() has been called.
20
21_info_ is an object containing "name", "size" and "type" of the selected file.
22
23And these mouse callbacks:
24
25* onmouseover(x,y)
26* onmouseout(x,y)
27* onmousedown(x,y)
28* onmouseup(x,y)
29* onmousemove(x,y)
30* onclick(x,y)
31* onrollover(x,y)
32* onrollout(x,y)
33* ondoubleclick(x,y)
34
35The mouse events are also triggered as regular jQuery events (i.e. `$('#input_replaced').rollover(function(){alert('over!')});` should work just fine as well).
36
37Every callback is scoped to the DOM element which has replaced the previous input (i.e. "this" in the callbacks points to the html element). Also by returning `true` in a callback function the default callback will be used.
38
39Which file types that can be selected may be defined with the _file\_types_ option, see the "Usage Example" below for more info. If none is defined all files are acceptable.
40
41
42Requirements
43-------------
44
45* jQuery 1.3+
46* SWFObject 2.1+
47
48Both available from Google AJAX APIs (recommended as it likely speeds things up).
49
50
51Example Usage
52-------------
53
54The HTML/JS part:
55
56	<script type="text/javascript" charset="utf-8" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>
57	<script type="text/javascript" charset="utf-8" src="http://ajax.googleapis.com/ajax/libs/swfobject/2.2/swfobject.js"></script>
58	<script type="text/javascript" charset="utf-8" src="jquery.s3upload.js"></script>
59	
60	<script type="text/javascript" charset="utf-8">
61		$(function(){
62			var max_file_size = 2 * 1024 * 1024; // = 2Mb
63			$("form").s3upload({
64				prefix: "s3upload/",
65				required: true,
66				onselect: function(info) {
67					if( parseInt( info.size ) < max_file_size )
68						return true; // Default is to show the filename in the element.
69					else
70						$(this).html("Too big file! Must be smaller than " + max_file_size + " (was "+info.size+")");
71				},	
72				file_types: [ 
73					[ "Images" , "*.png;*.jpg;*.bmp"], 
74					[ "Documents" , "*.pdf;*.doc;*.txt"]
75				]
76			});
77		});
78	</script>
79
80	<form action="/media/new" method="post" accept-charset="utf-8" enctype="multipart/form-data">
81		<label for="media_title">Title</label>
82		<input type="text" name="media[title]" value="" id="media_title" />
83		<label for="media_video">Video</label>
84		<input type="file" name="media[video]" value="" id="media_video" />
85		<label for="media_thumbnail">Thumbnail</label>
86		<input type="file" name="media[thumbnail]" value="" id="media_thumbnail" />
87		<input type="submit" value="Upload" />
88	</form>
89	
90	
91The Sinatra part (assumes the _s3upload_ gem is installed):
92
93	require "s3upload"
94	get "/s3upload" do
95	  up = S3::Upload.new( options.s3_upload_access_key_id , options.s3_upload_secret_key , options.s3_upload_bucket )
96	  up.to_xml( params[:key] , params[:contentType] )
97	end