Highly configurable cross-browser, ajax-based file uploader.
Displays a progress bar whilst uploading, allows restriction by filetype, and multiple file upload.
Based on Valums 'ajax uploader' javascript.
The Grails Ajax-Uploader plugin is a Grails Tag Library which implements
Andrew Valum's excellent file uploader.
Features
- Real progress-bar indication for upload progess
- Multi-file upload
- Javascript event callbacks
- No Flash required
- Works with all major browsers
- Easy to implement and robust Tag Library
- Customisable CSS, as well as a default CSS style if you're not bothered
- Fully tested source code, both Javascript, and TagLib
License
- GPL v2.0 - The source code contains all originally distributed files, without modifications
ConfigurationUse the following configuration, customising as neccessary
imageUpload {
temporaryFile = '/tmp/uploaded.file' // Path to where files will be uploaded
}Simply declare the 'fileuploader' module in your page, within the <head> tag, i.e:
<head>
<r:require module="fileuploader" />
<r:layoutResources />
</head>
To use a custom CSS file, see the
overriding section of the Resources plugin
For Grails 1.x, or if you're not using the Resources pluginSimply place the following in the HEAD block of your page:
To use your own CSS file use the head tag as follows:
<uploader:head css="/path/to/your.css" />
Study the uploader.css file to understand how your styles will affect the widget.
Creating an upload button in your pageIn the body of your page:
<uploader:uploader id="yourUploaderId" />
To use a custom endpoint to upload to, instead of the default /ajaxUpload/upload, use the uploader tag as follows:
<uploader:uploader id="yourUploaderId" url="${[controller:'yourController', action:'yourAction']}" />Study the AjaxUploadController to determine how to receive a streamed file, and return the required response.
Allowable attributes to the uploader tag| Attribute Name | Description | Allowed values |
|---|
| id | Id used for this instance of the uploader | String |
| url | Grails-style URL configuration map, or absolute url | Map/String |
| sizeLimit | Specifies a maximum size for uploaded files | Integer (>0) |
| minSizeLimit | Specifies a minimum size for uploaded files | Integer (>0) |
| debug | Turns debug (js console logging) on or off | String true/false |
| allowedExtensions | A list of allowed file extensions | String [ 'png', 'img', 'gif', … ] |
| params | Arbitrary name/value pairs to pass with the uploaded file | String ${[ param1:'value1', param2:'value2' ]} |
| messages | Custom Javascript validation messages | String |
| multiple | Enable/disable multiple uploads | String true/false |
Allowable attributes to the head tag
| Attribute Name | Description | Allowed values |
|---|
| css | specifies the path of your custom css file | String |
Callbacks for hooking into progress/completion eventsThere are currently four callbacks you can implement which will be triggered when the relevant event is fired by the script.
| Event | Tag | Callback parameters you have access to |
|---|
| onSubmit | <uploader:onSubmit> alert('file' + fileName + 'uploaded'); </uploader:onSubmit> | id, fileName |
| onProgress | <uploader:onProgress> console.log(loaded+' of '+total+' done so far') </uploader:onProgress> | id, fileName, loaded, total |
| onComplete | <uploader:onComplete> alert('file complete!'); </uploader:onComplete> | id, fileName, responseJSON |
| onCancel | <uploader:onCancel> alert('you cancelled the upload'); </uploader:onCancel> | id, fileName |
These callbacks must be nested within the uploader tag as follows:
<uploader:uploader id="yourUploaderId">
<uploader:onComplete>
$('statusDiv').update('Thank you for uploading the file '+fileName);
</uploader:onComplete>
</uploader:uploader>The variables you have access to in your javascript are:
- id: A file index number; the first file is assigned a value of 0 (zero)
- fileName: The name of the uploaded/uploading/cancelled file
- loaded: number of bytes uploaded so far
- total: number of bytes which are to be uploaded
- responseJSON: The JSON which was received from the uploader servlet
NoScript supportAs of version 0.3, the plugin now has configurable noscript support, meaning that if your user does not have javascript enabled, a simple form for uploading files using the traditional POST method can be included, which will only show if javascript is turned off. Alternately you could have a message telling the user to enable javascript, or get a decent browser.
The tag to do this is as follows:
<uploader:uploader id="yourUploaderId">
<uploader:noScript>
<p>Why don't you get a decent browser?</p>
</uploader:noScript>
</uploader:uploader>