^

Real Ajax Uploader logo

  • Facebook
  • Twitter
  • Google+
  • Pinterest

Documentation

Full documentation and options

Options:

Option Type Default Description
maxFileSize String '10M'

String: Set the maximum file size allowed for upload. Use as string to indicate unity: 500K for kylobytes, 10M for megabytes, 2G for gigabytes.

remotePath String, Function ''

String: If given as string specify the remote (server side) path where to upload the file.
Function: In given as function must return the remote upload path as string. This function is excecuted on the start upload event, so the upload path is calculated when Upload button is pressed. Can be usefull when path is calculated by any user choise (ex. form compilation).

url String upload.php The url action for the upload on server. More data can be pass in GET to the url: upload.php?customkey=customval
flash String uploader.swf The path of the flash swf file for no-HTML5 browser, multiupload support
data String, Function, Object '' String: If given as string is used for sending additional parameters in GET to the php script.
Function: If given as function must return a url formated string. This function is excecuted on the start upload event, so the data are created when Upload button is pressed. Can be usefull when need to send more data depending on user choise. Json Object: If given as object must have this format {getvar:value, anothergetvar:value....}. This is similar to jQuery Ajax data.
async Boolean true If true file uploads are made asyncronyos in parallel. If false files are uploaded one by one. Default to false for not html5 browsers
maxFiles Int 9999 Maxixum number of files that can be selected at once.
allowExt array [] An array containing the type of file extension that can be uploaded or selected. If empty all type of files can be selected. Recommended to be set on server side for security reasons.
enable Boolean true If set to false plugin start in disabled mode, in case one want to active upload later (using API functions) under certain conditions.
chunkSize Int 1024*1024 When uploading big files with html5 for perfomance reason is better to upload files by chunks. With this option set the size of chunk to upload. Defaul is 1Mb. Avaiable only for browsers that support slice File Api. Set to 0 if want to send all file at once.
dropColor string red Set the background color of the drop area during the upload by drag and drop. Can use #FFF values or RGB that css accept values.
dropClass string red Set the css class of the drop area during the upload by drag and drop.
dropArea jQuery selector/DOM element self Set the drag and drop area for files. Defaul the area is the initial container. Example can be set to dropArea:$('.class').
maxConnections Int 3 Set the maximum number of parallel file uploads. Avaiable only for browsers that support XmlHttpRequest File Upload. Maximum connections supported on Firefox are 6.
autoStart boolean false If true upload of files will start imediately after file choose.
thumbHeight int 0 Set the max height of thumbnial images to be generated on server side.
thumbWidth int 0 Set the max width of thumbnial images to be generated on server side.
thumbPostfix string _thumb Set the postfix of filenames of images.
thumbPath string same as remotePath set the path where thumbs should be saved, if empty path setted as remotePath.
thumbFormat String/Enum Same as original image Set the thumbnial format output image. Possible values jpg, gif and png
form String/ DOM,jQuery Object null Set the form to integrate with uploader. The file will be uploaded on form submit (like gmail attachments).
1.String: Can set a jquery selector, example #formId
2.String: If set as parent (form:'parent') it will try to find a parent form in the DOM tree.
jQuery Selector: Point to a form with a jQuery selector example $('#form_id')
editFilename boolean false If set true, allow the editing of file names before upload. Doubleclick on the file name and a text input will appear. On blur it will set the file name. Does not allow extension change.
sortable boolean false If set true, allow to sort the list of files before upload them, need jquery-ui.js . It is not usefull. Will be removed on the next versions
language String auto Used for translation the plugins strings. For the moment are avaible English, Italian, German, Francis, Netherland and Albanian translations. Set to auto for autodetecting the browser language, or use ISO codes for the avaiable languages: en_EN, it_IT, de_DE, nl_NL, fr_FR and sq_AL
uploadDir Boolean false Experimental feature. Works only on Google Chrome. Allow to select a directory and upload all its files.
removeOnSuccess Boolean false Set to remove file from the list when it has beed uploaded.
removeOnError Boolean false Remove the file from the list if it has returned any uploaded error and has not been uploaded correctly.
bootstrap Boolean false If true, to all buttons and elements will be added the Bootstrap classes, and if css bootstrap theme is included in the html document then the uploaded will have a bootstrap theme.
allowDelete Boolean false If true, files can be delete after upload. An upload button will appear for each file when it has been uploaded. Enable with combination on upload.php/upload.aspx for caution.
overrideFile Boolean false If set to true existing file with same name will be override on server, false files are renamed.
checkFileExists Boolean false If set to true user will be warned to continue upload or not when file already exists on server. Use in combination with override option.

Events, Callbacks:

Function Type Default Description
onInit function(AU Object) This function is run when on uploader initialization. Usefull if on init need to hide uploader elements (such as upload button or remove button) without editing the css. The AU parameter is the uploader instance class. For more details see the advance topic.
onSelect function(Array files) This function is trigger after files has been selected. It returns the array of selected files that has passed validation.
beforeUpload function(String filename) return true This function is trigger before every single file get uploaded. If this return false then the upload of the file does not start. Can be used when users need specific validation on file to get them uploaded
beforeUploadAll function(Array files) return true This function is trigger Upload All button is pressed. If this return false then the upload of all files will not start. Can be used to validate any condition before upload all files.
success function(String file_name) null A function that is trigger every time a file is uploaded successfully. Return the uploaded file name .
finish function(Array filesName, Array fileObjects) null This function is trigger when all files finish uploading. Returns an array with the file names and the array of the file objects ( for more see Advance api).
error function(String err, String fileName) null Function that is trigger when there is an error on uploading file. Returns error text and the file name. Error can be trigger also from the validateFile callback.
validateFile function(String name, String extension, Int size) null This funciton is called for each selected files, at the moment they are selected. This is similar to the onSelect callback, except that this is called for all selected files, and user can validate here a file. If this function return a error string the file will not be added to the list and the error string return will be catched by the error event.
fileInfo function(exifDaat) function(oData) { var strPretty = ""; for (var a in oData) { if (oData.hasOwnProperty(a)) { if (typeof oData[a] == "object") { strPretty += a + " : [" + oData[a].length + " values]\r\n"; } else { strPretty += a + " : " + oData[a] + "\r\n"; } } } alert(strPretty); } This function is called when the (i) button is pressed. This returns exif data for images. Works only on JPG file. Can be useful when need to extrac information for photos taken with camera or smartphones, for example for GPS data.

Methods, API:

Method Description Example
destroy Destroys the ajaxupload. $('.demo').ajaxupload('destroy')
option Set or get the options of the ajaxupload. getter: $('.demo').ajaxupload('option',allowExt) setter:$('.demo').ajaxupload('option',allowExt,['jpg','gif'])
enable Enable the plugin the ajaxupload plugin if it has been disabled. $('.demo').ajaxupload('enable')
disable Disables the plugin. $('.demo').ajaxupload('disable')
start A function to call for starting upload from other points of code, ie: on some extrenal button click. $('.demo').ajaxupload('start') starts uploading of selected files.
clear A function to call for clearing the queue of files ready to upload from other points of code, ie: on some extrenal button click. $('.demo').ajaxupload('clear') clear the list of selected files.
getAllowedExt Return the allowed extension setting. $('.demo').ajaxupload('getAllowedExt')
getFiles Return the selected files array with name, size, status and more. $('.demo').ajaxupload('getFiles')

How to integrate with forms:

Method 1: set to the uploader form DOM ID or selector

Example form:

<form class="form-horizontal" action="test.php" target="_self" id="contactform">
<input type="text" id="inputEmail" placeholder="Email">
<input type="text" id="inputName" placeholder="Name">
<button type="submit" class="btn">Send</button>	
</form>	

Uploader can setup, in any place:

<div id="uploader_div"></div>
<script type="text/javascript">
$('#uploader_div').ajaxupload({
url:'upload.php',
remotePath:'example1/',
form:'#contactform'
});			

The form option of the uploader has been set to the ID of the form we need to integrate. This methods does not need to edit your existing forms.

Method 2: set the uploader inside the form tags

Example form:

<form class="form-horizontal" action="test.php" target="_self" id="contactform">
<input type="text" id="inputEmail" placeholder="Email">
<input type="text" id="inputName" placeholder="Name">
<div id="uploader_div"></div>
<button type="submit" class="btn">Send</button>	
</form>	

Uploader can setup, in any place, but the uploader container should be inside the form tags:

<script type="text/javascript">
$('#uploader_div').ajaxupload({
url:'upload.php',
remotePath:'example1/',
form:'paret'
});			

The form option of the uploader has been set to 'parent'. In this case you need to insert the uploader div inside the form tags, at the wanted position.

NOTE: when integrating with a form and using option 1, be sure to call the ajax uploader after, the form element or on document ready event.

How form integration interact with the uploader

  • The submit event of the form is captured and stop by the uploader
  • The files start uploading
  • After all files are uploaded, to the original form are appended as many hidden inputs as the number of uploaded file. These inputs has the name ax-uploaded-files[], so on server side (PHP or ASPX) are sended the file names(full path)
  • After this, the original form is submited and all the above file name are sended

How Real Ajax Uploader works:

This jQuery plugin detect if XmlHttpRequest upload is supported as described on mozilla web site. This type of upload is supported by Firefox 3.6+, Safari 4+ and Chrome 4+. If html5 upload is not supported then flash is used . As well if flash is disabled then html4 standard upload is used.
HTML5 -> FLASH -> HTML4.
The suppport detect is done by detecting the support of the feature not detecting the browser. Actually Opera 11, Internet Explorer 9 does not support XmlHttpRequest upload but it seems that IE 10 will support it.

When selecting files a preview image of the file is display. If image type is JPEG, GIF, or PNG a real preview of image is show if this features is supported as described here. For other type of files or if image preview is not supported by the browser, a custom icon is shown to identify the type of file being uploaded. This icons can be configured and extended for each type of files by changing the css styles.

CSS styling

All style of plugin is based on CSS and some png images. Other css themes will be build and added to the plugin for free. All images, elements, buttons and divs created by the plugins have a CSS class. They can be simply viewed by looking and source code generated. Using this classes or changeing the CSS file all style can be customized.

By default Real Ajax Uploader has 5 themes:

  • Base theme (css/baseTheme/style.css) with round buttons and big icons, responsive
  • Classic theme (css/classicTheme/style.css) with normal buttons, responsive
  • Bootstrap theme (css/bootstrapTheme/style.css) a bootstrap base color theme, responsive
  • List theme (css/listTheme/style.css) with black-white icons, responsive
  • Fancy theme (css/fancyTheme/style.css)

Every theme can be customized and new theme can be added with css.

CSS classes

Every single element on the ajax uploader has a class, that starts by ax-CLASSNAME. This classes are use to style the uploader with the varius themes.

The list of classes uses for each element:

  • ax-uploader: the class added automatically to the uploader div
  • ax-main-title: class use by the main title, can be used to hide the title
  • ax-browse-c: class used to style the browse button
  • ax-upload-all: class used by the Upload All button
  • ax-clear: for the Clear button
  • ax-file-list: the clas applied the UL tag of file list
  • ax-prev-container: Class of the preview container
  • ax-preview: Class of the preview image inside the container
  • ax-button: class used by all button for the common settings
  • ax-upload: the single upload button
  • ax-remove: the single clear button
  • ax-file-name : the file name area
  • ax-file-size: file size area
  • ax-toolbar: class added to the container of the buttons

No javascript support fallback

If you want to support browsers where javascript is not enabled then when creating the uploader just create a normal upload form where the action point to the upload.php/upload.aspx file and the upload file inputs named ax-files. Real example:

	<!-- Create an iframe for ajax-like not-reloading-page upload  -->
	<iframe name="ax-main-frame" style="display:none;"></iframe>
	
	<!-- Create the  form: note the action value  -->
	<form id="uploader_fall" action="upload.php" method="post" encType="multipart/form-data">
	
	<!-- Set upload Path and other options -->
	<input type="hidden" value="example9/" name="ax-file-path" />
	<input type="hidden" value="100M" name="ax-maxFileSize" />
	<input type="hidden" value="jpg|gif|png" name="ax-allow-ext" />
	<input type="file" name="ax_file_input" />
	
	<!-- If need to generate thumbnail then set this option as hidden input -->
	<input type="hidden" name="ax-thumbHeight" value="100" />
	<input type="hidden" name="ax-thumbWidth" />
	<input type="hidden" name="ax-thumbPostfix" value="_thumb"/>
	<input type="hidden" name="ax-thumbPath" value="uploads/thumbs/" />
	<input type="hidden" name="ax-thumbFormat" value="png" />
		
		
	<input type="submit" value="Upload" />
	</form>

	<script type="text/javascript">
		$('#uploader_fall').ajaxupload({
			url:'upload.php',
			uploadPath:'example9/'
		});
	</script>

	<!-- Create the  form: note the action value  -->
	<form id="upload_with_fallback" action="upload.php" method="post" target="ax-main-frame" encType="multipart/form-data">

	

AU Objec Class and adavance usage

The Real Ajax Uploader is written with Javascript object (prototype) and has two main classes: the AjaxUploader class and the fileObject class. The AjaxUploader is the main class and holds all the reference and status the selected files, buttons, css and api-s. This class is added to the DOM element with the jQuery.data method, so It can be access and manipulated in real time after the uploader has been created:

	<script type="text/javascript">
		$('#uploader_div').ajaxupload();//create the ajax uploader
		var AU = $('#uploader_div').data('AU');
	</script>

AjaxUploader Class methods and proprieties:

  • AU.hasHtml4 : boolean tells if basic upload is supported
  • AU.hasAjaxUpload : boolean tells if html5 ajax upload is supported
  • AU.hasFlash : boolean tells if flash is installed for upload
  • AU.files : the list of files Object with the status and properties
  • AU.fieldSet : the container html element of the uploader, usefull if need to hide or change any inner element
  • AU.browse_c : the browse html (in jquery object) button that open the select file dialog window.
  • AU.uploadFiles : the upload html all button, usefull if you need to hide this button on the fly without editing the css
  • AU.removeFiles : the remove html button usefull if you need to hide this button on the fly without editing the css
  • AU.fileList : the UL list view with the selected files
  • AU.uploadAll() : function that starts uploading all files
  • AU.clearQueue() : function that remove all files from the queue (and from the list)
  • AU.removeFile(pos) : removes a file from the list of files, pos: the position of file in the array.

fileObject Class methods and proprieties:

The fileObject class holds all the information, status, buttons, progress of the single file. This object is created for every selected file and is added the the AU object queue (AU.files, the list of files objects):
		<script type="text/javascript">
			var AU = $('#uploader_div').data('AU');
			var file_list = AU.files;//get all the files object
			var file = file_list[0]; //a single fileObject
		</script>
	

fileObject methods and proprieties:

  • fileObject.file: the DOM file object
  • fileObject.currentByte: the current number of bytes uploaded
  • fileObject.status: the status of the file:0 ready, -1 error, 1 uploaded
  • fileObject.name: file name
  • fileObject.xhr: the XmlHttpRequest/Form DOM objects that upload the file
  • fileObject.info: file info aboust status
  • fileObject.ext: file extension
  • fileObject.info: file info aboust status
  • fileObject.pos: file position the in the queue (AU.files)
  • fileObject.AU: a reference to the AU class
  • All the follwing properties can be used to access visual elements, hide and change them on the fly
  • fileObject.prevContainer: image preview container dom element
  • fileObject.prevImage: preview image dom element
  • fileObject.details: file info container dom element
  • fileObject.nameContainer: name dom container
  • fileObject.sizeContainer: file size span container
  • fileObject.progressInfo: progress info container
  • fileObject.progressBar: progres bar
  • fileObject.progressPer: progress in percent container
  • fileObject.buttons: button container
  • fileObject.uploadButton: upload button dom element
  • fileObject.removeButton: remove button dom element

All the other methods and propriets of AjaxUploader class and of the fileObject class that are not documented here is because they are just private method not recommended to be used.

Bootstrap Theme

In the version 2.6 bootstrap theme support was added. Bootstrap provide a standard, responsive way of html5 web design. To use the bootstrap theme just load the bootstrap css and the ajax uploader bootstrap theme. For more see example 9.