Shift8 Creative Graphic Design and Website Development

Agile Uploader Documentation

Version 2.0

This is the documentation for Agile Uploader, regardless of the optional companion jQuery plugin (documentation for the plugin can be found here). It's broken into a few major sections to make it a little easier. There are many options to help you accomplish what you're after, but the most important feature to understand is how the Agile Uploader SWF works back and forth with JavaScript. I would personally suggest reading the overview first if you are new to Agile Uploader or you are looking for an explaination. The rest of the documenation is better for reference.

Old documentation for version 1.x can be found here.



Overview

The super quick overview is this: Agile Uploader is a SWF that gets embedded anywhere on your page (inside the form tags or outside or on a page without a form at all). It will allow the visitor to attach a file, usually an image but not necessarily. It can be one image or file or multiple with mixed types. The visitor submits this data to the server via a link or button in HTML that uses JavaScript to tell the SWF to post the data. When this happens, additional form data from the page may or may not be passed through JavaScript to the SWF to also send along with the file data. The post to the server is a multipart post. At that point, it's up to the server to handle. Agile Uploader will post to an address, this is typically the location of a script (such as a PHP or ASP script) that handles the incoming data.

Now let's go through this in a little more detail.

  1. The Agile Uploader SWF is embedded into a web page using swfobject or jquery.flash or any Flash embed method you like.
  2. With the embed there are flashvars that are set that include the URL that the swf is to post data to as well as settings for how file type restriction, number of files limit, total combined file size restriction, and many more settings.
  3. Another important setting is the name of the JavaScript function that the SWF will call to gather any additional form data that may be on the page. The form data must be serialized and returned. This is typically very easily a function that calls and returns jQuery's serlize().
  4. When the user attaches a file several things happen.
    1. Provided multiple files are allowed, two checks are made. The first looks for the maximum number of files limit and the second checks for the maximum file size limit of all combined files (after any resizing). If either fail, a JavaScript function is called if specified in the flashvars. This is a callback function and allows you, the developer, to notify the user of what went wrong.
    2. Once the file has been loaded from the user's computer into Flash, another callback can be called This is the attach callback. Flash will send the file name, file extension, and a unique id for the file. This id is useful for referencing the file in situations where you want to allow the user to remove the file from the list of files to be sent to the server. Provided multiple files are allowed to be posted and you want to allow the user to remove any of them.
    3. We now have a few more potential callbacks. If the file is an image and a resize is needed, the page will be notified via JavaScript about the current image's encoding progress in real time. The function will be called multiple times with the current encoding percentage. This allows you to display a progress bar using JavaScript (jQuery UI has a nice one) or simply display a spinner until complete.
    4. There is an optional encoding complete callback that can be used as well. Typically you may use the preview callback to know when this event happens or you may do the math and say 100% encode progress means it's complete. However, this complete callback is there should you need it.
    5. Now, regardless of whether or not the file is an image, a preview callback can be called. This is important to use if you want to display information such as final file size. It gets called for all file types, but if the file happens to be an image, a preview thumbnail will be returned. This is a data URI. So please understand that Internet Explorer 6 and 7 can not use this base64 encoded string to display an image preview. Internet Explorer 8 can. If you're using the companion jQuery plugin, a check is made to see if the browser supports data URIs and if not, a generic icon will be used. This is a setting within the jQuery plugin though.
    6. There are some other JavaScript functions that get called and things you can do, I will call these "callbacks" just the same even though they are now going the other direction and are making calls to methods within the SWF. These allow the user to do things like remove files that are curently attached and waiting to be posted to the server.
    7. In the event the uploader is set to only send one file, the attached file will be overwritten by any newly attached file.
  5. After all files are attached (one or multiple), another JavaScript function must call the method within the SWF to post the data to the server. Right before this happens, there is another callback that can be used to gather any form data from the page that is to also be sent along with the file(s).
  6. After the submit happens, the response from the server can be sent to yet another JavaScript callback function. This also serves the purpose to tell if the submission was successful. It returns the server response so you can use the uploader in more of an "AJAX" fashion where you don't re-direct the user to another page. Or, using JavaScript, you can now re-direct the user to another URL.

Still with me? Good, as you can tell there's a lot of things that go on and you are definitely kept in the loop every step of the way. Flash and JavaScript work together to make all the magic happen.

Not with me? That's ok too. If you're using a browser with firebug, you can turn on a firebug debug option in the flashvars so Flash will send messages to your browser's firebug console every step of the way. It will report information like names and sizes of files attached, if any resizing was required, server response codes, and more. Very helpful to see the entire process.

Embedding

I personally would suggest using swfobject or jQuery.flash for embedding, but you can of course embed this any way you'd normally embed a swf. There's a few things you should know though.

  • Embed with allowscriptaccess set to "always" so that Flash and JavaScript can communicate back and forth.
  • Be sure that the minimum Flash player version required to view the swf is 10.0.0 (very important, the features within the swf are new in version 10).
  • Be sure that you give the player and id and are aware of it in order to utilize the ExternalInterface and access methods within the swf.
  • Watch the height and width settings of course and understand that there are required flashvars to be set (though many are optional).

If you choose to use the companion jQuery plugin, you only need to make sure that swfobject or jQuery.flash script is included on the page. The Agile Uploader jQuery plugin will detect methods provided by those scripts and use either one to do the embed (it looks for and uses jQuery.flash first, having both scripts on your page should not cause an issue or double embed, but why would you have both?).

Flashvars

The flashvar settings allow you to fully customize what Agile Uploader looks like and how it works. You are able to upload not just a single or multiple files, but also upload any file type you like. You can control the obvious things like image resize dimensions and quality, but also the more advanced things like how that encoding should be handled. Then there's many more settings that you might find handy. Note the values of these variables. If there are quotes around the values, they are strings. This is important for things like boolean values - there are none - they are all strings that say true or false.

form_action

required
The "form action" URL that you'd normally see in the HTML code (where to submit the form data to). The data is sent via POST and is multipart.

js_get_form_data

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 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.

return_submit_response

default: 'false'
If set to 'true' then the server response will be returned to the submit_complete JavaScript callback function as the first argument. This is useful for "AJAX" style posts. Note: You can't send headers to the server with Flash (such as x-ajax headers) yet. You can with an AIR app, but not currently with a Flash swf. So you can't have a server script detect the post as an AJAX post or even being posted from Flash (again an AIR feature not a Flash feature). You'll need to post along other form variables and be a little creative if you need to do some sort of detection like that.

max_post_size

default: 0 (specified in kilobytes)
The maximum limit for the size of all attached files combined in kilobytes, 0 signifies unlimited. Note that this does not include other form data gathered from the page. Even though it will in all likeliness be small (just text) it could add up and push you over a server limit. So be aware of that.

file_filter

default: '*.jpg;*.jpeg;*.gif;*.png;*.JPG;*.JPEG;*.GIF;*.PNG'
Which file extensions to allow. You may wish to also include capitalized versions as well. Flash does make a distinction between the case of the file extension (not sure if this is true for all operating systems or not). Note that non image files will not be resized.
Warning: Be VERY careful to ensure whatever script handles the posted data checks for potentially dangerous files or scripts. Flash's file filter should filter out file types, but that doesn't mean someone can't see where you're posting data to and use some tool to send the POST request with whatever data they want. At that point, it would have nothing to do with Agile Uploader...Just while we're on the subject here of file types, it's worth mention.

file_filter_description

default: 'Images'
When the popup dialog appears for the user to select a file to attach there is usually a drop down or something that describes the type of files that they can attach since the list they will see is filtered. You may want this small visual clue to say something like "Files" or "Photos" depending on the file types you're allowing and your needs/preferences.

resize

default: 'jpg,jpeg,gif,png'
Which file extensions to resize. If you change the default string list (separated by commas, no spaces) you can effectively bypass resizing on certain image types. This can be useful if you don't care about the size uploaded and needed to preserve transparency for PNG images (for now, still working on getting a PNG encoder) or just wanted full size images instead of setting maximum dimension limits to something very large.

file_limit

default: 0
The file limit. 0 allows for unlimited file attachments. -1 allows for only one attachment that will be replace with each new attached file. 1 would allow for one attachment, but it would first need to be removed before another attachment could replace it. Any other number, same deal -- when you reach the limit, you'll need to remove files before being able to attach more.

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.

fill_color

default: '0xffffff' (white)
Transparent gif and png images can be resized, but they get encoded as jpeg for now, sorry. There are plans to also encode to png, maybe even gif one day. For now though that means your transparent images get flattened (only when resized). So you have to choose a matte color. It's white by default, but you can set it here using an RGB value or also a web hex (be sure to put # in front of your web hex value).

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.

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's a thin line and 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)

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

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

The location of the graphic to use for the "over" or hover state of the attach button.

button_down

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

There's some more flashvars that can be passed and these are the names of JavaScript callback functions. If specified, these functions get called by the Flash swf for certain events such as encoding status, completion, messages from the server, and so on. This completes the puzzle so to speak by tapping in to give you complete control and awareness.

js_submit_callback

1st argument (dependent), string: Any returned data from the server (useful for AJAX style submits)
The name of the javascript function to call when the form data has been submitted by Flash. The 1st argument will be passed from Flash if the "return_server_response" flashvar is set to 'true' (see above).

js_status_callback

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

1st argument, string: The name of the file attached
2nd argument, string: The file extension for the file attached
3rd argument, string: A unique id for the file attached
The name of the javascript function to call when files are loaded and fully attached. This is a very handy callback. It's actually necessary if you want to allow the user to remove any of the attached files (in the event of multiple file handling). It also can be used to display the name of the attach file(s) somehwere on the page to notify the user.

js_max_post_size_callback

1st argument, string: The name of the last file attempted to be attached
2nd argument, string: The unique file id of the last file attempted to be attached
The name of the javascript function to call when combined size of all attached files are beyond the specified limit.

js_file_limit_callback

1st argument, string: The name of the last file attempted to be attached
2nd argument, string: The unique file id of the last file attempted to be attached
The name of the javascript function to call when the maximum number of allowed file attachments goes over the set limit.

js_encode_callback

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

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

1st argument, string: The preview image base64 string
2nd argument, string: The file name
3rd argument, string: The file extension
4th argument, string: The file size in kilobytes
5th argument, string: The unique file id within the swf used to reference the file
The name of the javascript function to call that Flash sends the preview image to. All files will fire this callback if defined even if they are files that do not get resized. The reason is because in addition to the preview image data, the file size and other data is passed. This is useful for displaying information to the user that we can't get (if images are resized) at the time of attachment. NOTE: The image data is a special base64 encoded string (data URI) and is not compatible with Internet Explorer 6 or 7.

js_preview_encode_callback

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 just before the preview callback (which sends the image to the page to be displayed, see above). Most likely you can kinda ignore this one. 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 because it does take time to encode and you may want to show a spinner or something in the meantime.

Flash Methods

Going the other direction from JavaScript to Flash, there are several methods available to you. The biggest one is going to of course be the submit method so you can actually post the data to the server. Then there's a few more. You're going to call these by referencing the embedded swf's object id. So for example: document.getElementById('agileUploaderSWF').sendForm(); ... would call the sendForm method within the swf.

sendForm()

You'll need to call this method in order to post the data to the server. In previous version of Agile Uploader, the swf itself could include a submit button (button in Flash) so this wasn't required. However, with additional features, the file size of the swf increased so space was saved by removing this submit button in the swf. It also increases flexibility because you can choose when to call the submit and it would probably be rare that you'd want the submit button to be within the Flash because of this and for other reasons like design.

removeFile(file_id:string)

This method will allow you to remove an attached file (provided multiple files are allowed) by referencing it's unique id. The unique id is passed on several callbacks (see above) so you'll need to use one in order to keep track of the id values.

removeAllFiles()

This method will allow you to remove all currently attached files.