Super file upload

  • Tags : file upload
  • Latest : 0.4
  • Last Updated: 24 June 2009
  • Grails version : 1.1 > *
  • Authors : Peter Delahunty
6 votes
Dependency : 
compile ":super-file-upload:0.4"

Documentation

Summary

Description

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

<sfu:fileUploadControl/>

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.