Attachmentable Plugin

  • Tags: file upload, attachment
  • Latest: 0.3.0
  • Last Updated: 05 October 2012
  • Grails version: 1.1 > *
4 votes
Dependency:
compile ":attachmentable:0.3.0"

 Documentation  Source

Summary

A plugin that allows you to add attachments to domain classes in a generic manner.

Installation

grails install-plugin attachmentable

Description

Attachmentable Plugin

This plugin provides a generic way to add and manage attachments for a given application. It is based on 2 JQuery plugins:

Requirements

  • Grails Version: 1.2.1 and above
  • JDK: 1.5 and above

Installation

grails install-plugin attachmentable

Configuration

  1. The default one looks like:
grails.attachmentable.maxInMemorySize = 1024
grails.attachmentable.maxUploadSize = 1024000000
grails.attachmentable.uploadDir = YOUR_USER_HOME/APP_NAME

2. You need to define a poster evaluator in grails-app/conf/Config.groovy. The default one looks like:

grails.attachmentable.poster.evaluator = { request.user }

But if you store users in the session instead you may want this to be:

grails.attachmentable.poster.evaluator = { session.user }

Or, if you use the Acegi plugin:

grails.attachmentable.poster.evaluator = { getAuthUserDomain() }

Or in case of the Spring Security Core Plugin:

grails.attachmentable.poster.evaluator = { getPrincipal() }

In version 0.2.0 and above poster can be a String:

grails.attachmentable.poster.evaluator = { "unknown" }

3. Searchable plugin

You can let the searchable plugin index you attachments using the Apache Tika parser. Install the searchable plugin and add this to your Config.groovy:

grails.attachmentable.searchableFileConverter="attachmentFileConverter"
You can then search for text inside your attachments in PDF, Word, Excel and many other document formats. Note that the current implementation will only index the first 2 MB of text, to conserve memory.

Usage

You have two options.

Implement the Attachmentable interface:

import com.macrobit.grails.plugins.attachmentable.core.Attachmentable

class Topic implements Attachmentable { }

or

Add a static property

class Topic {
  static attachmentable = true
}

Add some attachments:

GSP:

<input type="file" name="pictures"/>
<input type="file" name="pictures"/>
<input type="file" name="pictures"/>
…
<input type="file" name="movies"/>
<input type="file" name="movies"/>
…
<input type="file" name="someLabel"/>
...

or

<attachments:style />

<attachments:uploadForm bean="${topicInstance}" />

<attachments:script updateInterval="100"/>

Controller:

attachUploadedFilesTo(topicInstance)

Query:

def topic = Topic.get(1)

// get

def attachments = topic.attachments def pictures = topic.getAttachments('pictures')

// count

def attachmentsNo = topic.totalAttachments def picturesNo = topic.getTotalAttachments('pictures') def mediaNo = topic.getTotalAttachments(['pictures', 'movies'])

// remove

topic.removeAttachments() topic.removeAttachments(['pictures', 'movies'])

topic.removeAttachment(attachmentInstance) topic.removeAttachment(attachmentId) topic.removeAttachment('pictures')

To remove all attachments when the "owner" domain is deleted, add this to your domain:

transient def beforeDelete = {
    withNewSession{
        removeAttachments()
    }
}

It's important to wrap the method call in withNewSession { … } See http://jira.codehaus.org/browse/GRAILSPLUGINS-2386

In a GSP:

<attachments:each bean="${topicInstance}">
    <attachments:icon attachment="${attachment}"/>
    <attachments:deleteLink
                         attachment="${attachment}"
                         label="${'[X]'}"
                         returnPageURI="${createLink(action: 'actionName', id: topicInstance.id)}"/>
    <attachments:downloadLink
                         attachment="${attachment}"/>
    ${attachment.niceLength}
</attachments:each>

To add some logic to handle newly created attachments, just add an "onAddAttachment()" method to your Attachmentable domain class:

class Topic implements Attachmentable {

def onAddAttachment = {attachment -> // post processing logic for newly added attachment }

}

Internationalization

  • check the "messages.properties" file from the plugin directory.

Tags

deleteLink

AttributeDescription
attachmentThe attachment instance.
labelThe link label (also you can use the body tag instead of this attribute).
returnPageURIThe page URI to return after the action.

downloadLink

AttributeDescription
attachmentThe attachment instance.
inlinetrue if attachment should be viewed inline in the browser.

each

AttributeDescription
beanThe attachmentable instance.
inputNameThe input name.
inputNamesThe list of input names.
varThe name of the item (default: 'attachment').
statusThe name of a variable to store the iteration index in. For the first iteration this variable has a value of 0, for the next, 1, and so on.

total

AttributeDescription
beanThe attachmentable instance.
inputNameThe input name.
inputNamesThe list of input names.

style

AttributeDescription

script

AttributeDescription
inputNameThe file input name (default: 'attachment').
importJSBoolean value: insert or not the JS files.
updateIntervalThe update interval(in milliseconds) for the progress bar.
maxFilesThe maximum files allowed.
acceptExtAccepted extensions.
updateElemIdThe ID of the element that will be updated with the response data.
redirectURL to redirect to when file upload is finished.

uploadForm

AttributeDescription
beanThe attachmentable instance.
inputNameThe file input name (default: 'attachment').
styleClassThe style class.

progressBar

AttributeDescription

icon

Generates an <img> tag with an appropriate icon based on file type, using a subset of the Silk Icons.

AttributeDescription
attachmentThe Attachment instance

Version History

  • 0.3.0 (October 5, 2012) - Updated dependencies and uploaded source to github.
  • 0.2.1 (January 14, 2011) - Fixed problem with spring security plugin.
  • 0.2.0 (January 5, 2011) - Optional searchable indexing of files. Icons.
  • 0.1.1-SNAPSHOT (June 4, 2010) - Some small fixes/enhancements.
  • 0.1-SNAPSHOT (March 17, 2010) - First release.

Suggestions, comments or bugs

Feel free to submit questions or comments to the Grails users mailing list. Alternatively you can contact me directly - cazacugmihai at gmail dot com

Please report any issues to the Grails users mailing list and/or write up an issue in JIRA at http://jira.codehaus.org/browse/GRAILSPLUGINS under the Grails-Attachmentable component.