Super File Upload Plugin
Overview
This plugin provides support for a file upload progress bar. It uses http://swfupload.org/ and also the jquery progress bar plugin http://t.wits.sg/misc/jQueryProgressBar/demo.php
Author: Peter Delahunty
blog: http://blog.peterdelahunty.com
twitter: http://twitter.com/peterdelahunty
email: peter.delahunty@solution51.com
Compatibility
The plugin is currently compatible with version 1.1.x of grails.
Installation
Installation is very simple as is all grails plugin installations;
grails install-plugin super-file-upload
Documentation
Usage of the super file upload plugin is very simple. All you need to do is add the following gsp tags within your page.
Head setup grails tag :
This generates the javascript. It has lots of parameter i will discuss below. Here is a simple tag. You MUST put this tag in your head element on your html page.
<sfu:generateConfiguration fileSize="30" form="bookForm" buttonImageFile="/buttons/browse-button-sprite.png" buttonWidth="104" buttonHeight="30"/>
File upload control grails tag
Drop this where you want the file upload control to be rendered
Progress bar grails tag
Drop this where you want the progress bar to be rendered
<sfu:fileUploadProgressBar/>
IMPORTANT html Form element onsubmit attribute
You must also supply the onsubmit attribute on the form. This must call the sfuSubmitForm function. Just copy the example above. If you don't do this then nothing will work :)
<form id="bookForm" name="bookForm" onsubmit="return sfuSubmitForm(this);">
Full example of a gsp page with a form.
This assumes you have a button image at the url /buttons/browse-button-sprite.png. See more info about the button below.
<html>
<head>
<title>Simple form test</title>
<sfu:generateConfiguration fileSize="30" form="bookForm" buttonImageFile="/buttons/browse-button-sprite.png" buttonWidth="104" buttonHeight="30"/>
</head>
<body><form id="bookForm" name="bookForm" action="save" onsubmit="return sfuSubmitForm(this);"> Choose file: <sfu:fileUploadControl/>
<br/>
Progress bar: <sfu:fileUploadProgressBar/>
<br/> <input type="submit" value="Save">
</form></body>
</html>How to handle in your controller
You need to look out for a parameter call uploadedFileId
class DemoController { SuperFileUploadService superFileUploadService def save = { String uploadFilename = params.uploadedFileId if (uploadFilename) {
// get the full path name of the file from the temp directory
File file = superFileUploadService.getTempUploadFile(uploadFilename) }else{
// file was not uploaded by flash. User might have javascript off
def fileStream = request.getFile('sfuFile');
// handle normal file upload as per grails docs
} redirect(action:'confirm)
}}sfu:generateConfiguration Attributes
form:(required)
This is the name of the form you want to submit after the file upload has completed. It is the id of the form.
controller(optional)
This the name of the controller that you want to call to handle the file upload. All calls default to /sfuReciever/handleFlashUpload if you do not specify
controller(optional)
This the name of the action that you want to call to handle the file upload. All calls default to /sfuReciever/handleFlashUpload if you do not specify
fileSize(optional)
This is the fileSize limit in MB of the file being uploaded. It defaults to 10MB. An alert message is thrown if it bigger than this limit
paramName(optional)
This is the http parameter name of file data being uploaded. It is default to 'sfuFile'. Note if you change this you must all change the name on the fileUploadControl tag.
buttonImageDir(optional)
This is the base directory of where button image sprite image lives. It defaults to images
buttonImageFile(optional)
This is the name of button image sprite image. See below about the rules for the button image
buttonWidth(optional)
The width of the button
buttonHeight(optional)
The height of the button
progressBarBoxImg(optional)
The outer box image for the progess bar
progressBarImg(optional)
The progress bar image
progressBarHeight(optional)
The progress bar image height
progressBarWidth(optional)
The progress bar image width
useEmbeddedJquery(optional)
Use this and set to false if you use your own version of jquery already on the page. Otherwise to do use it
cssClass:(optional)
This is the css class for the text box. You can put as many as you like separated by a space.
sfu:fileUploadControl Attributes
paramName:(optional)
This is the http parameter name of file data being uploaded. It is default to 'sfuFile'. Note if you change this you must all change the paramName on the generateConfiguration tag.
sfu:fileUploadProgressBar Attributes
cssClass:(optional)
This is the css class for the progress bar. You can put as many as you like separated by a space.
Super file upload configuration
You have two configuraiton options that you specify in the config.groovy of your project.
sfu.tempUploadDirectory
This the place where you want the uploaded file to be saved.
example
sfu.tempUploadDirectory = "c:/swf_temp"
sfu.paramName
This is the http parameter name of file data being uploaded. It is default to 'sfuFile'. Note if you change this you must all change the paramName on the generateConfiguration tag and the fileUploadControl tag
h2 Image button rules
Your image button must be an image sprite and contain 4 variations of the button:
normal, hover, click, disabled
Just like this:
Or this
Graceful degredation
This plugin supports Graceful degredation. So if the user does not have javascript enabled or flash support then it just default to the normal file upload control.
Screen shots
Here is a screen shot from my web site using this plugin. http://www.ebookstamper.com
With the flash control rendered
With Progress bar
Falling back to normal file upload because javascript is disabled.
flash javascript
Fisheye
Docs
Edit Plugin
Close