Agile Uploader Documentation
I do plan on making this a better looking "API" style documentation. Perhaps code highlighting and the use of something like doxygen. For now you'll just have to excuse appearances, but this should have everything you need.
Back to Overview
General Usage
Example Embed Code
Example Process Code (PHP)
Configuration (flashvars)
JavaScript Callbacks (more flashvars)
General Usage Notes
Embedding Agile Uploader should be fairly straight forward. I'd suggest swfobject to embed it and pass the flashvars. The only truly required flashvar is the "form_action" one which specifies where the data should be sent to. This might be a PHP script that then processes the data and saves to a database or whatever.
Agile Uploader has been tested with image file sizes in excess of 4MB, but posting large files is all up to your server settings. The intended use of Agile Uploader though is really to resize before uploading...So most images being posted are expected to be under a megabyte. The tool currently only submits one version of the image, so if you're looking to store a full size version and a thumbnail version of the image, you will need to find some other solution (this could change in the future though).
Also, you can only upload one file at a time right now. Of course since the Flash can post the form without navigating the user away from the page, you could set things up to allow multiple images to be posted in a more "AJAX" type manner. The images just won't all be sent at the same time. This is definitely something that will change in the future and it the uploader will still remain simple in design. More than likely what is going to happen will be an image is processed and set to be posted, a call to a JavaScript function is made to notify the page the file has been processed...It's name and file size...Then it will be on you to show this information in a list somewhere. This would allow for complete customization. There might be a flash list as well, but that really commits the design to have a big box somewhere on the page. Anyway, more to come. For now check out the configuration options below.
Example Embed Code
Here's an example embed using swfobject...It is the same embed code found on the main page and includes the use of two callbacks. In this case we are sending the form data to Flash using jQuery's "serialize()" function. So you would need jQuery with this embed code. Then also on the callback that lets us know the form data was submitted, there's a simple JavaScript function here that re-directs to the results page. You can also see the settings for the max width and height as well as quality, form action and other settings. Of course these flashvars could be one object instead of being defined property by property on each line, this just helps you visualize the options better.
function serializeData() { return $("#theform").serialize(); }
function submitted() { window.location = "http://www.shift8creative.com/agile-uploader/results.php" }
var flashvars = {};
flashvars.max_height = 250;
flashvars.max_width = 250;
flashvars.jpg_quality = 85;
flashvars.file_input_field_width = 200;
flashvars.form_action = '/agile-uploader/process.php';
flashvars.js_get_form_data = 'serializeData';
flashvars.firebug = true;
flashvars.flash_submit = false;
flashvars.js_submit_callback = 'submitted';
var params = {};
params.allowscriptaccess = "always";
var attributes = { id: "ExternalInterface" };
swfobject.embedSWF("/agile-uploader/agile-uploader.swf", "myContent", "310", "30", "10.0.0","expressInstall.swf", flashvars, params, attributes);
Then of course the html parts, which would include the rest of the form, the Flash embed and submit button. Note in this case the submit button is just a text link.
Submit
Example Process Code (PHP)
Then you will need to handle the form POST data with some sort of script on your server that can write the file to disk and do whatever else you need to do. Here is an example using PHP. In this example we aren't saving the form data to a database or anything like that, we're just writing the form data to a file. The text file is being overwritten in this case each time the form is submitted to the script (this is just for the demo).
$target_path = "/full/path/to/upload/folder";
$text_file = $target_path."post_data.txt";
$fh = fopen($text_file, 'w') or die("can't open file");
fwrite($fh, "Title: ".$_POST['title']."\n");
fwrite($fh, "Another Field: ".$_POST['testdata']);
fclose($fh);
$tmp_name = $_FILES["Filedata"]["tmp_name"];
$name = $_FILES["Filedata"]["name"];
move_uploaded_file($tmp_name, "$target_path/$name");
Configuration Options (flashvars)
form_action (required)
The "form action" URL that you'd normally see in the HTML code (where to submit the form data to).
js_get_form_data (optional)
The javascript function that gathers form data from the page to hand off to Flash to post. You most likely will use this if you are posting anything more than just an image. Note: It's probably easiest to just make a function that calls jQuery's "serialize()" function for this.
file_post_var (default: 'Filedata')
The post variable key name that holds the file data. In Apache/PHP for example this default is: $_FILES['Filedata']
max_width (default: 300)
Agile Uploader will resize images to fit. So the largest dimension will be used (if image is larger). This is obviously the max width. Do not put "px" at the end.
max_height (default: 300)
...And of course the max height. Again, do not put "px" at the end, this is just a number.
preview_max_width (default: 300)
The preview image will also be resized (and that means encoding may take place) to fit this dimension. If this and the preview_max_height are the same or greater than the main resized image dimensions, the main image will also be used as the prevew image. There's no need to resize and encode twice. It also would be strange to have a preview image that is larger than the final image that ends up the server. Again, don't put "px" on the end here.
preview_max_height (default: 300)
...And of course the prewview max height. Again, do not put "px" on the end.
jpg_quality (default: 85)
This is the encoding quality (it does matter) and I personally believe anything 85 and above looks pretty darn good. Note that the higher you make this, the longer it takes to encode.
preview_jpg_quality (default: 65)
If the preview image ends up needing to be resized and encoded, this is the quality to encode at. It is by default lower than the final image to help encode faster, since it's just a preview.
pixels_per_iteration (default: 128)
This is an advanced setting, probably shouldn't mess with it. It could crash people's browsers. However, it basically sets the encoding "speed" for lack of better words. You shouldn't have to mess with it unless maybe you're not really resizing images and you want to encode larger images faster.
browse_button_text (default: 'Browse')
What you want the button to say that a user clicks to attach an image. (Note: in the future this will be a completely customizable button allowing you to specify images, but for now it is a button with text).
show_file_input_field (default: 'true')
You know that text input type field to the left of the "browse" button? This is it and while it's married to the normal HTML file input element, you can ditch it with Agile Uploader.
file_input_field_height (default: 21)
The height of this input field. Do not put "px" at the end. This is a number value not a string.
file_input_field_width (default: 200)
The width of this input field. Do not put "px" at the end. This is a number value not a string.
show_encode_progress (default: 'true')
This will show the progress bar below the input field. It fits snug right underneath and it's width is determined by the input field's width.
encode_progress_color (default: '0x00ff00' - green)
The color of that encoding progress bar. It can be rgb or web hex style, ie. #000000 (please put the # symbol if specifying web hex)
file_input_field_width (default: 200)
The width of this input field. Do not put "px" at the end. This is a number value not a string.
flash_submit (default: 'false')
Show the submit button in Flash. More than likely you're using this uploader so you can put the submit button where ever you like. However, you can include it within the Flash if you'd like.
flash_submit_position (default: 'right')
The position of that flash submit button. By default it just sits to the right of the "browse" button. Possible positions include; "right", "bottom_left", and "bottom_right".
submit_button_text (default: 'Submit')
Should explain itself, much like the browse button text, you can control the Flash submit button text.
submit_complete_input_text (optional)
The input text field's copy when submission is complete. Probably fairly useful for when the user is not navigated away from the page after submitting.
submit_complete_reset_progress (default: 'true')
Reset the progress bar on submission complete. Again, perhaps useful when the visitor is not navigated away as it can help with the illusion of "resetting" the upload field. This setting won't really matter though if the use is re-directed after submitting.
button_up (optional)
The location of the graphic to use for the "up" or normal state of the attach button. Defining all three states will use a custom button instead of the default to allow people to attach files.
button_over (optional)
The location of the graphic to use for the "over" or hover state of the attach button.
button_down (optional)
The location of the graphic to use for the "down" or click/hit state of the attach button.
firebug (default: 'false')
A handy feature for debugging. This will enable a bunch of message logging to the firebug console. This includes information about the resizing of the image, post status, error codes, and so on. You don't want to enable this of course unless you have firebug installed and you also don't want to leave it on after you're done.
Callbacks (more flashvars)
js_submit_callback (optional)
The name of the javascript function to call when the form data has been submitted by Flash.
js_status_callback (optional)
1st argument, string: The HTTP status code
The name of the javascript function to call and pass the status code to when submitting the form data. This is the Flash httpStatusEvent. It will pass along a code to the function as the first argument, ie. 404, 200, etc. This might be handy for troubleshooting and error handling.
js_attach_callback (optional)
1st argument, string: The name of the file attached
The name of the javascript function to call when a user attaches an image. This might be handy to disable/enable a submit button or pop-up some sort of message, etc. This fires at the moment when Flash receives the image data, not exactly when the user clicks on the file to attach. So there is a lag time and that depends on the size of the file. It used to be immediately after the user clicked a file and the dialog choose file closed, but that's not helpful for things like loader bars that want to appear and start moving the very second the image begins to resize and encode.
js_encode_callback (optional)
The name of the javascript function to call when the image encoding is complete. In conjuntion with the above callback, perhaps here is where that submit button is turned back on. This could be used to prevent the user from submitting the form before the image was processed.
js_encode_progress_callback (optional)
1st argument, number: The percentage complete for encoding
The name of the javascript function to call to report the encoding progress (as it's encoding). This could be very useful with something like jQuery UI's progress bar. Or any other kind of progress event you'd like to use.
js_preview_callback (optional)
The name of the javascript function to call that Flash sends the image to. The data that Flash sends to this function is safe to use in an HTML image's src attribute or within CSS, XML, and so on. This is a special base64 encoded string. NOTE: The image preview is not compatible with Internet Explorer 6.
js_preview_encode_callback (optional)
1st argument, string: The image to be used in an HTML image tag or elsewhere
The name of the javascript function to call when the preview image has completed encoding and can just before the preview callback (which sends the image to the page to be displayed, see above). This is probably only useful if you really must guarantee that the user sees the preview image. Typically speaking, the preview image should already use the encoded "main" or final image that will be sent to the serer or it will be encoded very quickly because it's a small dimension and of lower quality. However, for those who want to send along large images to the server and have large previews, this could prove useful.
