Agile Uploader jQuery Plugin Documentation
Version 2.0This is the documentation for the companion jQuery plugin for Agile Uploader. The purpose of the plugin is to provide a quick and easy way of embedding a single or multiple file upload widget. This plugin and the use of jQuery at all is completely optional in order to use Agile Uploader. It's a popular JavaScript library so it seemed like a good idea to provide this.
Overview
The super quick overview is this: the plugin JavaScript file gets included in the page along with either the swfobject or jQuery.flash script. Then a div with an id on the page gets one of the Agile Uploader jQuery plugin methods applied to it. The div is magically transformed into an upload widget. A submit link or button is placed anywhere on the page and that calls a method in the plugin which in turns tells the Flash to submit the form to the server and away goes the data.
Now let's go through this in a little more detail.
- The Agile Uploader plugin is included (typically you'll use the minified version to save on bandwidth).
- Swfobject is also included let's say (again you can use jQuery.flash plugin).
- You have a div on the page with an id of "myDiv"
- Inside a script block, a call to plugin is made and options are passed, for a single file image upload (with resize to default dimensions) it can be as simple as: $('#myDiv').agileUploaderSingle({submitRedirect: 'results.php', flashVars: { form_action: 'process.php' }}); ... Though it's probably a little more elaborate.
- On a link or button or within a script block somewhere that waits for an event (like a click) a call is made to submit the data to the server using, $().agileUploaderSubmit();
Methods
There's a few methods that the jQuery plugin provides. Mainly they are responsible for embedding upload widgets and post the data to the server.
agileUploaderEmbed(options:object)
Probably the one you're after if you're looking for multiple file uploads. Calling this will take a div and transform it into a basic looking multiple file upload widget. You can customize the CSS to make it look different, change the colors, icons, etc. but it will end up having a certain look to it. The only argument it takes is an object with all the settings including flashvars that end up being used when the swf is embedded.
agileUploaderSingle(options:object)
A very basic upload widget that only allows one file to be uploaded per submit call. This is the most basic usage of Agile Uploader.
Options Object
Default values are specified here for each key followed by a description in parenthesis.
- flashSrc: 'agile-uploader.swf'
(string, the location of the swf) - flashWidth: 25
(number, this sets the width of the embed area for the swf) - flashHeight: 22
(number, this sets the height) - flashParams: {allowscriptaccess: 'always'}
(object, this passes flash params, you shouldn't need to define it) - flashAttributes: {id: "agileUploaderSWF"}
(object, this passes attributes, again you shouldn't need to define it) - flashVars: { form_action: ..., file_filter: '*.jpg;*.jpeg;*.gif;*.png;*.JPG;*.JPEG;*.GIF;*.PNG', file_filter_description: 'Files', max_post_size: 1536, file_limit: 0, return_submit_response: 'true', max_height: 500, max_width: 500, jpg_quality: 85, preview_max_height: 50, preview_max_width: 50, show_file_input_field: 'false', show_encode_progress: 'false', button_up:'add-file.png', button_over:'add-file.png', button_down:'add-file.png' }
(required object, the only required value in this object that you must define is form_action and it is a string that is the path to post the data to. This is a big one and you will need to define other options only if you want to customize things like file limit, type restrictions, etc. You can see the defaults listed here, but see the documentation on flashvars for more) - progressBar: '#000000'
(string, web hex value this is for the progress bar that the plugin creates in html, not the progress bar within the swf) - attachScrollSpeed: 1000
(number, when files are attached the list grows, it automatically scrolls to show the last item...this defines how fast to scroll) - removeIcon: 'trash-icon.png'
(string, the location of the remove icon that the plugin outputs in the list of attached files) - genericFileIcon: 'file-icon.png'
(string, when previews are not available, IE6/7, this image will be used and for any file that is not an image, this image will be used as an icon in the attachment list) - maxPostSizeMessage: 'Attachments exceed maximum size limit.'
(string, the text to display in below the attachment area when the combined size of all files is too large) - maxFileMessage: 'File limit hit, try removing a file first.'
(string, the text to display when the number of files limit has been hit) - removeAllText: 'remove all'
(string, the linked text to show above the attachment lists to remove all files) - submitRedirect:
(string, where to redirect to after submit) - formId:
(string, the DOM id of the form so that the plugin can gather the data from it to post along with the attachments, don't define this if you don't have a form or don't want to post the values from it)
agileUploaderSubmit()
This function just wraps the "sendForm" method in the swf that sends the data to the server. Part of what happens after executed is the swf gathers any serialized form data (provided that callback is defined, see above) and then submits any attached file(s) to the server. It gets a response and if told to (again in the options) will call another JavaScript callback (with optional response text returned). Then if a redirect was specified in the options, the visitor will be redirected after the submission is complete.
