Criteria Plugin

  • Tags: functionality
  • Latest: 1.6
  • Last Updated: 12 May 2010
  • Grails version: 1.3.0 > *
  • Authors: Paul Fernley
2 votes
Dependency:
compile ":criteria:1.6"

 Documentation

Summary

Description

Criteria Plugin

Description

This plugin allows the user to limit the display of records, typically on a 'list' page, by specifying a property to be tested, the test to perform and, where applicable, the value(s) to test against. Only domain properties with a Hibernate 'basic data type' (including enumerations) can be tested. The tests available are: equal, not equal, is null, is not null, less than, less than or equal to, greater than, greater than or equal to, like, not like, between, not between, in and not in.

Installation

Execute the following from your application directory:

grails install-plugin criteria

The installation process copies a properties file called criteria.properties to the i18n directory of your application overwriting any file of the same name.

Usage

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

import org.grails.plugins.criteria.*

The between and not-between tests accept two values separated by space, ampersand, space as in: 23 & 47. The in and not in tests accept a list of arguments separated by space, vertical bar, space as in: fiction | non-fiction | reference. Date values must be entered strictly in the format yyyy-mm-dd or yyyy-mm-dd hh:mm if a time is to be included. Tests against boolean properties accept the values true or false. Enumeration values must be entered in their constant form (e.g. FICTION, NON_FICTION etc)

To include a criteria selection facility in a GSP simply include a <g:criteria/> tag in the page at the point where you would like the criteria form to appear. A common place to put the criteria tag is just after the flash messages (assuming you are using a scaffold-like page structure). It is also common to put the criteria tag within a div for formatting purposes, thus:

<div class="criteria">
    <g:criteria/>
</div>

A typical entry in main.css might be something like the following:

.criteria {
    border: 1px solid #b2d1ff;
    background: #f0f8ff;
    margin: 10px;
    padding: 4px;
    text-align: center;
    color: #006dba;
    font-weight: normal;
    font-size: 14px;
}
.criteria input.apply {
    background: #b2d1ff;
}

If your controller name is NOT in the format domainController, then you must add a domain attribute to the criteria tag identifying the domain class that the criteria is to affect:

<g:criteria domain="Book"/>

By default, the criteria plugin will display all properties of the domain in its property selection list that have a Hibernate basic data type, including id, version, dateCreated and lastUpdated. You may exclude properties from being displayed by specifying an exclude attribute in the criteria tag:

<g:criteria exclude="id, version"/>

Conversely, you may use an include attribute in the criteria tag to specify only those properties that should be displayed in the property selection list (subject to the 'basic data type' limitation), thus:

<g:criteria include="name, dateOfBirth, language"/>

To refer to embedded properties in an include or exclude list, use 'dot' naming convention such as: homeAddress.zipCode where homeAddress is the property that represents an embedded class and zipCode is a property of that embedded class.

In your controller, you need to change the creation of the model from something like:

[bookInstanceList: Book.list(params), bookInstanceTotal: Book.count()]

to:

[bookInstanceList: Book.selectList(session, params), bookInstanceTotal: Book.selectCount(session, params)]

If you have the drilldowns plugin installed, then the above changes will be familiar to you since the criteria and drilldown plugins coordinate between themselves to limit the records being displayed by the page.

There will be certain 'starting points' in your application where all criteria should be cleared. This typically occurs in menus. To clear all criteria, include a <g:criteriaReset/> tag in the menu GSP. Alternatively, you can do this programatically from within, say, a controller using criteriaService.reset(session).

At certain points within your application, you may wish to clear a specific set of criteria, rather than all of them. This can be done programatically from within, say, a controller by using the criteriaService.removeCriteria(session, key) method where the 'key' parameter is in the format controller.action. The drilldown plugin, if installed, will automatically clear the criteria as it moves up and down its drilldown stack.

Compatibility

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

If you have the help-balloons plugin installed, the <g:criteria/> tag will include online help in the criteria form. The criteria plugin uses a message bundle for all its texts so that you may internationalize it if you wish or, if you have the localizations plugin installed, the texts will be taken from the database automatically.

The criteria plugin looks for property names in your message bundles/database using the i18n-templates plugin format of domain.property (e.g. book.title etc). If you have the menus plugin installed, the displayed menus will automatically reset any criteria each time a menu is 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) Minor bug fixes

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