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