Drilldowns Plugin

Description

The drilldowns plugin allows a user to drill down from a summary level screen to a more detailed level. For example, from a list of authors to a list of books by the selected author. It works by controller and action - usually the 'list' action. Each controller/action combination may only appear once within the drilldown stack, whether as the 'drill from' list or the 'drill to' list. Any list page can be both a 'drill from' and a 'drill to' page thus allowing the creation of the 'stack' of drilldowns.

Installation

Execute the following from your application directory:

grails install-plugin drilldowns

The installation process copies two files (drilldown.png and drillup.png) to the images directory of your application overwriting any files of the same name.

Usage

The components of the plugin are in a package called org.grails.plugins.drilldown and any class that wishes to access the components directly must include the following:

import org.grails.plugins.drilldown.*

In a 'drill from' page (i.e. a GSP) displaying, say, a list of authors, within the loop displaying each author you would include a new column using code similar to the following:

<td><g:drilldown controller="book" action="list" value="${authorInstance.id}"/></td>

Such a column might be headed 'Books'. The attributes of the drilldown tag are as follows:

• controller - The name of the 'drill to' controller.
• action - The name of the 'drill to' action (defaults to 'list')
• domain - If the 'drill from' controller name is NOT in the format domainController then you must identify the domain being drilled from (e.g. domain="Author"). Defaults to the controller name capitalized to make it a domain name.
• value - The id of the 'drill from' instance that the 'drill to' display is to be limited to.
• text - Any text to display as the drilldown link. Default is no text. If text is supplied then, by default, this would stop the automatic display of any image.
• encodeAs - How to encode any text attribute e.g. encodeAs='HTML'. Default is no encoding (thus allowing HTML markup to be included).
• image - If set to true, forces the display of the default image even when a text attribute exists. When set to a URL, uses the image at that URL (even if there is also text).
• imageAfter - When both text and an image are to be displayed within the drilldown link, specifies whether the image is to be displayed before (false) or after (true) the text. The default is after (true).

def drilldownService
def list = {
  params.max = Math.min(params.max ? params.int('max') : 10, 100)
  def ddAuthor = drilldownService.source(session, params, "author.list")
  def ddPub = drilldownService.source(session, params, "publisher.list")
  [bookInstanceList: Book.selectList(session, params),
      bookInstanceTotal: Book.selectCount(session, params),
      ddAuthor:ddAuthor, ddPublisher:ddPub]
}

You must call the drilldownService.source() method at least once before using the selectList method - even if you are not interested in the object it might return. If the 'drill to' controller name is NOT in the format domainController, then you must identify the domain being drilled down to with a 'domain' option as in:

drilldownService.source(session, params, "author.list", [domain:"Book"])

If the book domain contains more than one property of type Author, then you must specify which property the drilldown system should use, as in:

drilldownService.source(session, params,"author.list", [property:"reviewAuthor"])

The above options can, of course be combined, as follows:

drilldownService.source(session, params, "author.list",
                        [domain:"Book", property:"reviewAuthor"])

Assuming, in the above example, that the 'drill from' controller/action was 'author.list' then ddAuthor would contain an instance of the Author domain to which the list of books should be limited. ddPub would be null. If the book list action had been called directly from a menu, then both ddAuthor and ddPub would be null. This fact can be used in the rendered book list GSP as follows:

<g:if test="${ddAuthor}">
  <h1>Book List for Author: ${ddAuthor.name} <g:drilldownReturn/></h1>
</g:if>
<g:elseif test="${ddPublisher}">
  <h1>Book List for Publisher: ${ddPublisher.name} <g:drilldownReturn/></h1>
</g:elseif>
<g:else>
  <h1><g:message code="default.list.label" args="[entityName]" /></h1>
</g:else>

The drilldownReturn tag in the above example accepts the same text, encodeAs, image and imageAfter attributes as for the drilldown tag described above.

There may be various 'starting points' within an application (typically menus) where the drilldown stack should be cleared, just in case the user jumped directly back to such a starting point without working their way back through the drilldown stack. To clear the drilldown stack within a menu GSP, simply include the <g:drilldownReset/> tag. To clear the stack from within a controller, simply use drilldownService.reset(session).

When a user drills down from, say, an author listing to, say, a listing of the books for a chosen author, then if they press the New Book link to create a new book it can be helpful to pre-select the author of the new book to match the 'drill from' author. This can be done by adding a line in the create method of the book controller that utilizes modified parameters to the 'source' facility described previously. For example:

def create = {
  def bookInstance = new Book()
  bookInstance.properties = params
  bookInstance.author = drilldownService.source(session,
      [controller: params.controller, action: "list"], "author.list")
  return [bookInstance: bookInstance]
}

Compatibility

This plugin was written using Java version 1.6u18 and Grails version 1.3.0.

If you have the criteria plugin, this drilldown plugin will automatically coordinate with the criteria plugin when limiting the list of 'drill to' items to be displayed.

History

Version 1.6. (2010-05-12) Update to Grails v1.3

Version 1.5. (2009-12-30) Update to Grails v1.2

Version 1.4. (2009-04-03) Update to Grails v1.1 and packages

Version 1.3. (2009-02-01) Fix for error when sorting

Version 1.2. (2009-01-22) Reload due to SVN wobbly

Version 1.1. (2009-01-21) Fix for many-to-many bug

Version 1.0. (2008-11-18) Initial release