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.

1. Bird's Eye Overview

2. Embedding
3. Flashvars
4. Callbacks (flashvars and much more)
5. Flash Methods (call these using JavaScript)

1. Bird’s Eye 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.

2. 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?).

3. 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.
 4. 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.
 5. 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.