Grails 3 plugin for manage versioned files.
Groovy Shell Batchfile Java
Switch branches/tags
Clone or download

README.adoc

Grails 3 Versioned Files plugin

Introduction to the Grails 3 Versioned Files plugin

The Grails 3 Versioned Files plugin adds support to attach files to domain models. It was intially inspired by great attachmentable plugin which at the time was limited to grails 2. Main difference is with this plugin you can attach files and manage their versions.

Supported operations:

  • attach

  • detach

  • upload (brand new file or new version of existing one)

  • move to trash

  • empty trash

  • group in buckets

  • show

  • download (if no version selected, latest is downloaded)

  • find

Installation

Add the dependency in build.gradle:

dependencies {
   ...
   compile 'tools.blocks:grails3-versioned-files-plugin:{project-version}'
   ...

You only need to set these properties in application.yml or application.groovy:

annexable:
    repositoryPath: /home/user_name/annexable_docs
    bucket: test
    userName: user_name

where:

  • repositoryPath - path to the directory in file system

  • bucket - name of directory associated with the application where files will be stored

  • userName - it can be userName as String or Closure returning user name as String

Usage

To enable Annexable interface you have two options, static property:

Book.groovy
package com.mycompany

class Book {

   static annexable = true

   ....
}

or implement Annexable interface:

Book.groovy
package com.mycompany

class Book implements Annexable {

   ....
}

From now you can use your domains as files container.

Annex domain model

Contains meta information about file like type, size, version or name.

AnnexableDomain domain model

Allows to link your domain models with files (annexes).

AnnexableControllerTrait

All controllers are enhanced by this trait. Methods added:

Table 1. Methods added to controllers classes
Method Description

findAnnex

Allows to find annexes by part of the name of file and bucket

uploadAnnex

Allows to upload file as new Annex object or new version of existing one

attachAnnex

Allows to attach existing Annex object to your domain object

detachAnnex

Allows to detach previously attached Annex from your domain object

showAnnex

Same as downloadAnnex method but with changed headers

downloadAnnex

Allows to download file (if no version is set then the latest one will be used)

AnnexableController

Contains same methods as these added by AnnexableControllerTrait. It can be used instead of enhanced controllers methods.

AnnexableService

Contains methods which operate on FileRepo helper class.

Tags library

Namespace of AnnexableTagLib is annexable. It use boostrap, jquery and font-awesome (not included).

Tags supported by this plugin (Boostrap version)

annexesDomainPanel

Panel for use with domain model. Contains full set of operations, with search for attach. Can be treated as an example or can be used as complete solution. Example of usage in gsp:

Property Description

bean

Domain model to use with

controller

Controller name to handle requests (if not set annexable will be used)

name

Name of HTML element (if not set annex will be used)

bucket

Name of bucket (if not set common will be used)

<annexable:annexesDomainPanel bean="${testAnnex}" controller="testAnnex" name="annexes" bucket="testBucket"/>

upload

Tag for upload file. File can uploaded as new version of existing Annex or brand new Annex. It can be also linked with existing domain model if specified.

Property Description

bean

Domain model to use with (if set new Annex will be linked with model)

controller

Controller name to handle requests (if not set annexable will be used)

bucket

Name of bucket (if not set common will be used)

uploadAnnexId

Identity of Annex object (if not set new Annex will be created)

<annexable:upload bean="${testAnnex}" controller="testAnnex" uploadAnnexId=1 bucket="testBucket"/>

download

Tag for downloading file with particular version. Tag displays versions of the Annex.

Property Description

annex

Annex domain model to download

controller

Controller name to handle requests (if not set annexable will be used)

<annexable:download bean="${testAnnex}" controller="testAnnex" />

show

Tag to display file content. It’s implemented as iFrame, so iframeId must be specified and points to existing HTML element.

Property Description

annexId

Id of existing Annex object

controller

Controller name to handle requests (if not set annexable will be used)

iframeId

Id property of HTML iFrame element (must be set and exists)

<annexable:show annexId=1 controller="testAnnex" iframeId="showIFrame"/>

attach

Tag for attaching Annex to domain model.

Property Description

bean

Domain model to attach to

annexId

Id of existing Annex object

controller

Controller name to handle requests (if not set annexable will be used)

fileName

Name of the file to attach (optional, just for display on button)

<annexable:attach bean="${testAnnex}" annexId=1 controller="testAnnex" fileName="test annex.png" />

detach

Tag for detach Annex from domain model.

Property Description

bean

Domain model to detach from

annexId

Id of existing Annex object

controller

Controller name to handle requests (if not set annexable will be used)

<annexable:detach bean="${testAnnex}" annexId=1 controller="testAnnex" />

History

Versions:

  • 0.1.0

    • First release with complete set of methods, controller enhance trait, service and files operations helper.

  • 0.1.1:

    • Created by and Edited by fields handling

  • 0.2.1:

    • Move to Grails 3.2.11

    • Package rename

    • New tag

    • Redirect after upload based on params

  • 0.2.2:

    • Allow multiple annexesMiniDomainPanel tag (one per bucket)

    • Fixes related to application contextPath

  • 0.2.3:

    • Flash message added to controller trait

Roadmap

  • Version 0.3.0:

    • Non bootstrap tags

    • Bucket per domain (configurable)