Ajax Uploader Plugin

  • Authors: Antony Jones
8 votes

3% of Grails users

Dependency:
compile ":ajax-uploader:1.1"
Custom repositories:
mavenRepo "http://repo.desirableobjects.co.uk/"

 Documentation

Summary

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.

Installation

grails install-plugin ajax-uploader

Description

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
Configuration

Use the following configuration, customising as neccessary

imageUpload {
  temporaryFile = '/tmp/uploaded.file' // Path to where files will be uploaded
}

Usage

Basic usage

For Grails 2.0 and later, or if you're using the Resources plugin

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 plugin

Simply place the following in the HEAD block of your page:

<uploader:head />

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 page

In the body of your page:

<uploader:uploader id="yourUploaderId" />

Advanced Usage

Custom Upload Controller

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
idId used for this instance of the uploaderString
urlGrails-style URL configuration map, or absolute urlMap/String
sizeLimitSpecifies a maximum size for uploaded filesInteger (>0)
minSizeLimitSpecifies a minimum size for uploaded filesInteger (>0)
debugTurns debug (js console logging) on or offString true/false
allowedExtensionsA list of allowed file extensionsString [ 'png', 'img', 'gif', … ]
paramsArbitrary name/value pairs to pass with the uploaded fileString ${[ param1:'value1', param2:'value2' ]}
messagesCustom Javascript validation messagesString
multipleEnable/disable multiple uploadsString true/false

Allowable attributes to the head tag

Attribute Name Description Allowed values
cssspecifies the path of your custom css fileString

Callbacks for hooking into progress/completion events

There are currently four callbacks you can implement which will be triggered when the relevant event is fired by the script.

EventTagCallback 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 support

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

<uploader:noScript />

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>