FilterPane Plugin

Help Grails be an active, open community! If you use this plugin and haven't rated it, please do so. If you've rated this plugin anything but 5 stars, please let me know why (See #Support for how). I'm striving to make this plugin the best that it can be, and constructive feedback is always appreciated.

This plugin adds filtering capabilities to any Grails application. The primary goals of this plugin include:

• Easy integration with Grails list pages via custom tags
• Smart operator display. Only practical filter operations are available for a property's data type. (e.g. no "like" operators for numeric properties)
• Support for major operators including =, <>, >, <, >=, <=, like, ilike, between, is null, and is not null.
• Smart filter value entry. Date properties display a date picker, boolean's display radio buttons, etc.
• Support for a custom list of values, such as a filtering a text property with a constrained list of values.
• Works with Grails list sorting out of the box with only minor modification to your list gsp.
• Works with Grails pagination out of the box with only minor modification to your list gsp.
• Honors domain constraints: nullable, blank, inList ( Since 0.4 )

Please note that you may experience duplicate rows if you use eager fetching. See http://jira.codehaus.org/browse/GRAILSPLUGINS-2063 for more information.

Index

• #Usage
• #list.gsp
• #Pagination
• #List Sorting
• #Controller
• #Examples
• #Plugin Version History
• #Roadmap
• #Support
• #Reference
• #Data Types and their Available Filter Operators
• #Text
• #Numeric
• #Date
• #Boolean
• #Enum
• #Tags
• #currentCriteria
• #filterButton
• #filterPane
• #isFiltered
• #isNotFiltered
• #paginate
• #Internationalization (i18n)

Usage

list.gsp

1. Add the javascript and stylesheet includes to the head section of your page.

<filterpane:includes />

2. Somewhere in your page (typically near the bottom of the body tag), add the filter pane. This has the result of rendering a container div in your page.

<filterpane:filterPane domainBean="MyDomainClass" />

3. Add a button to invoke the filter pane somewhere on your list page. (Inside the pagination div works well on applications built from scaffolding.) A custom tag is provided to help create this button. The title attribute is optional. If omitted, the value of the button will be "Filter".

<filterpane:filterButton text="Whatever You Wish" />

If your application uses scriptaculous and you use the filterButton tag, the filter pane will fade in and out. Otherwise the filter pane simply appears and disappears.

Pagination

<g:paginate total="${bookCount == null ? Book.count(): bookCount}" params="${filterParams}" />

Note that you should not use Groovy's Elvis operator to test for bookCount's existence, as an empty set (count of 0) will return false, thus causing Book.count() to be used. See Groovy Truth for more info.

Also in the example above, filterParams is set in the model map of the render call in the controller. The value is a sub-map of the request params, and can be obtained by calling the "extractFilterParams" method on the included FilterUtils class. See the example below from the books example app.

render( view:'list', 
    model:[ bookList: filterService.filter( params, Book ), 
        bookCount: filterService.count( params, Book ), 
        filterParams: com.zeddware.grails.plugins.filterpane.FilterUtils.extractFilterParams(params), 
        params:params ] )

Starting with version 0.6 of the plugin, you can use the new paginate tag. The paginate tag wraps the Grails paginate tag and encapsulates the steps listed above. See the #paginate tag for more info.

List Sorting

<g:sortableColumn property="id" title="Id" params="${filterParams}" />

Controller

1. Inject the filter service into your controller.

def filterService

2. Create the filter action in your controller.

def filter = {
    if(!params.max) params.max = 10
    render( view:'list', 
        model:[ domainClassList: filterService.filter( params, DomainClass ), 
        domainClassCount: filterService.count( params, DomainClass ), 
        filterParams: com.zeddware.grails.plugins.filterpane.FilterUtils.extractFilterParams(params), 
        params:params ] )
}

Where…

• domainClassList is the name of the return list model the list action uses
• DomainClass is the name of the domain class you are filtering
• domainClassCount is the name of a variable that contains the total number of filtered results. This parameter is optional, but is useful if you want to use Grails pagination (which most of the time you will).
• filterParams is a sub-map of the request parameters obtained via the FilterUtils.extractFilterParams method.

Keep in mind that you don't have to name the action "filter". You can name it anything you want, just remember to assign the same name to the filterPane tag's action attribute so your action gets called when applying the filter.

Examples

Plugin Version History

Roadmap

• Minor versions of 0.6 will address issues that arise with 0.6 and any critical bugs that are found.
• Revised documentation that is more user friendly and improved examples of each feature.
• Release 0.7 will focus on adding more unit and functional tests and simplifying the code base.
• Future releases will be kept smaller than 0.5 and 0.6 in an attempt to deliver changes faster.

Support

• For support questions, please use the Grails user mailing list (user@grails.codehaus.org), and include the word "filterpane" somewhere in your message.
• JIRA issues may be found here.

Reference

The reference section is only applicable to versions 0.4 and above. Version 0.4 addressed some redundancy in the tag and attribute names provided by the plugin. While all previous attribute names are still supported, it is recommended to use those documented below instead. The deprecated tag and attribute names may be removed in the future.

Data Types and their Available Filter Operators

Text

Numeric

Date

Boolean

Enum

Domain Constraint Modifications

Tags

includes

currentCriteria

filterButton

filterPane

filterPropertyValues="${[someDateProperty:[years:2015..1999]]}"

filterPropertyValues="${['author.lastName':[values:Author.executeQuery('select t.lastName from Author t')], 'readPriority.name':[values:ReadPriority.list()]]}"

<form id="author-form" name="author-form" method="post">
	 <filterpane:filterPane id="author-filter-pane" domainBean="com.zeddware.grails.plugins.filterpane.Author"
            associatedProperties="books.title, books.bookType"
            titleKey="fp.tag.filterPane.titleText" customForm="true"
	    formName="author-form"/>
	<g:actionSubmit value="Apply Filter From Outside Filter Pane" action="filterCustomForm" />
</form>

isFiltered

isNotFiltered

paginate

Internationalization (i18n)

Filter Operators

• fp.op.ILike
• fp.op.NotILike
• fp.op.Like
• fp.op.NotLike
• fp.op.Equal
• fp.op.NotEqual
• fp.op.IsNull
• fp.op.IsNotNull
• fp.op.GreaterThan
• fp.op.GreaterThanEquals
• fp.op.LessThan
• fp.op.LessThanEquals
• fp.op.Between

Property Name Display

Filter Button Tag

• fp.tag.filterButton.text
• fp.tag.filterButton.appliedText

Filter Pane Tag

• fp.tag.filterPane.titleText=Filter
• fp.tag.filterPane.property.boolean.true=Yes
• fp.tag.filterPane.property.boolean.false=No
• fp.tag.filterPane.property.betweenValueSeparatorText=and
• fp.tag.filterPane.sort.orderByText=Order by
• fp.tag.filterPane.sort.noSelection.text=Select a Property
• fp.tag.filterPane.sort.ascending=Ascending
• fp.tag.filterPane.sort.descending=Descending
• fp.tag.filterPane.button.cancel.text=Cancel
• fp.tag.filterPane.button.clear.text=Clear
• fp.tag.filterPane.button.apply.text=Apply

The full default message bundle can be found in the installed plugin's folder in the messages-filterpane.properties file.

The plugin supports the i18n Templates plugin's domain property format:

<domainClass>.<property> <-- for each property