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.

6.1 Data Types

Data Types and their Available Filter Operators

Domain Constraint Modifications

If a property is not nullable (constraint nullable="false"), the Is Null and Is Not Null operators will not be available for that property.

6.1.1 Text

Text

(String, char)

Operator	Select Option Display Text
ILike	Contains
ILike	Begins With (Using no leading wild-card eg: ilike 'foo%')
Not ILike	Does Not Contain
Like	Contains (Case Sensitive)
Not Like	Does Not Contain (Case Sensitive)
"="	Equal To
<>	Not Equal To
Is Null	Is Null
Is Not Null	Is Not Null

6.1.2 Numeric

Numeric

(Integer, Long, Short, Float, Double, BigDecimal, BigInteger)

Operator	Select Option Display Text
"="	Equal To
<>	Not Equal To
<	Less Than
<=	Less Than or Equal To
>	Greater Than
>=	Greater Than or Equal To
Between	Between
Is Null	Is Null
Is Not Null	Is Not Null

6.1.3 Date

Date

Operator	Select Option Display Text
"="	Equal To
<>	Not Equal To
<	Less Than
<=	Less Than or Equal To
>	Greater Than
>=	Greater Than or Equal To
Between	Between
Is Null	Is Null
Is Not Null	Is Not Null

It appears that grails date picker does not currently support seconds input. This may cause the equals operator or between to return unexpected results. You may need to take that into account when using filters to be inclusive and round up or down to the next second when filtering.

6.1.4 Boolean

Boolean

Operator	Select Option Display Text
"="	Equal To
<>	Not Equal To
Is Null	Is Null
Is Not Null	Is Not Null

6.1.5 Enum

Enum

(since 0.6)

Operator	Select Option Display Text
InList	In List
NotInList	Not In List

6.1.6 Class

Class

(since 2.3)

Operator	Select Option Display Text
InList	In List
NotInList	Not In List

The class attribute is covered by the filter only if a filtered domain class has some implementers (only not abstract implementers are covered). This gives the ability to filter entries based on their domain class.

Filtering by class is available only if table-per-hierarchy is true as in the example below

static mapping = {
    tablePerHierarchy true
}

6.2 Tags

6.2.1 includes

includes

Deprecated - Please use the included resources module `filterpane` on the pages you wish to use default functionality/styling.

Deprecated - Style and script include has moved to use asset pipeline. See usage >= 2.4.3 below.

The includes tag should be used in the head section of your pages. It includes the necessary stylesheet and javascript file for the plugin.

Attribute Name	Required	Default Value	Description
css	No	true	Set to false to exclude the <link> tag for the stylesheet.
js	No	true	Set to false to exclude the <script> tag that supports the filterPane plugin.

Usage (>= 2.4.3)

<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
  <meta name="layout" content="main"/>
  <title>Robot List</title>
  <asset:javascript src="fp.js"/>
  <asset:stylesheet src="fp.css"/>
</head>

Usage (>= 2.1.6)

<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
  <meta name="layout" content="main"/>
  <title>Robot List</title>
  <r:require module="filterpane" />
</head>

Deprecated Usage (< 2.1.6)

<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
  <meta name="layout" content="main"/>
  <title>Robot List</title>
  <filterpane:includes/>
</head>

6.2.2 currentCriteria

currentCriteria

This tag renders an unordered list of the currently applied filter criteria, along with links to remove individual filter criteria.

Attribute Name	Required	Default Value	Description
domain	Yes	None	The domain bean being filtered. May be a String (e.g. "Book") or a class instance (e.g. ${Book})
id	No	filterPaneCurrentCriteria	The id of the unordered list.
title	No	None	The title attribute for the unordered list.
class	No	None	The CSS class to apply to the list.
style	No	None	The style attribute for the list.
dateFormat	No	yyyy-MM-dd HH:mm:ss	The format to apply when displaying date criteria.
action	No	filter	The controller action to submit to when removing criteria. Set this to the same as your filterPane tag's action attribute.
removeImgDir	No	None	The directory the remove image file is located in.
removeImgFile	No	None	The image filename to be used for the remove link. Note that if either removeImgDir or removeImgFile are missing, the text "(X)" will be used for the remove link.
quoteValues	No	True	(Since 2.0.1) If true, values will be quoted when displayed.
filterPropertyValues	No	None	(Since 2.0.1) Identical syntax to the filterpane tag's property of the same name. Use this to set a display property of enum properties. See example below.

filterPropertyValues

<filterpane:currentCriteria domainBean="org.grails.example.nested.Robot" dateFormat="${[title: 'MM/dd/yyyy', releaseDate: 'MMM dd, yyyy']}"
                              removeImgDir="images" removeImgFile="bullet_delete.png" fullAssociationPathFieldNames="no"
                              filterPropertyValues="${[robotType: [displayProperty: 'display']]}"/>

Template

This uses _filterpane/_currentCriteria.gsp

6.2.3 filterButton

filterButton

This tag renders an HTML link that shows the filter pane when clicked. When one or more filters are applied, this button will have the filter-applied css class.

Attribute Name	Required	Default Value	Description
text	No	"Filter"	The text that is displayed on the button.
appliedText	No	"Change Filter"	The text displayed on the button when one or more filters are applied.
id	No	"filterpane"	The id of the html element.
textKey	No	"fp.tag.filterButton.text"	The message bundle key that contains the text of this button. (i18n)
appliedTextKey	No	"fp.tag.filterButton.appliedText"	The message bundle key that contains the applied text of this button. (i18n)

<filterpane:filterButton text="Filter Me" appliedText="Change Filter"/>

Template

This uses _filterpane/_filterButton.gsp

6.2.4 filterPane

filterPane

This tag generates the filter pane itself. As of release 0.4, this tag pulls as much filtering information from the domain class as possible by default. All attributes from 0.3.1 are still supported, but are considered deprecated in favor of more sensible alternatives.

Attribute Name	Required	Default Value	Description
domain	Yes	None	The name of the Grails domain class to be filtered. This can either be a string (e.g. "Book"), or an actual class instance (e.g. "${Book}")
dialog	Yes	False	Set to true to cause the rendered filterpane to be displayed as a popup dialog instead of rendered inline in the page.
title	No	"Filter"	The title text that is displayed at the top of the filter pane.
titleKey	No	None	A message bundle key for looking up title text. (i18n)
id	No	"filterpane"	The id of the container div that holds the filter pane.
class	No	None	The class attribute to add to the container div that holds the filter pane.
style	No	None	The style attribute to add to the container div that holds the filter pane.
formName	No	"filterForm"	The name of the filter form element. Useful if you will use custom javascript on the form.
formMethod	No	"post"	The method to be used for the filter form.
filterProperties	No	None	If specified then no default properties are included, only those specified.
associatedProperties	No	None	Use this if you wish to filter any properties of associated domain objects (e.g. author.lastName). The value may either be a comma-delimited string, or a List of strings.
additionalProperties	No	None	By default, identifier, version, and lastUpdated properties are not available to filter by. Use this attribute to allow them to be filtered. The value may either be a comma-delimited string, or a List of strings. Valid values are "id", "identifier", "version", and "lastUpdated"
excludeProperties	No	None	By default all persistent properties of the domain object are filterable. If you wish to exclude any properties from filtering, specify them in this attribute. The value may either be a comma-delimited string, or a List of strings.
action	No	"filter"	The controller action to call when the filter is applied.
filterPropertyValues	No	None	A map of property values to pass through to each property's value form control. For example, since Date properties render a date picker control, you could pass the following to limit the years in the date picker. See the example below. It is also possible to specify a valueMessagePrefix parameter here which will make it possible to localize enum values in a list. See g:select tag.
customForm	No	false	If true or "true", the tag will not render the surrounding form or the "Apply" button on it. This is left to the developer. This attribute is useful if you want to embed the filterpane form in an existing form. (since 0.6.4) See the example below:
listDistinct	No	false	If true or "true" this will cause any one<->many or many<->many relationship where search criteria on a child matches to only return distinct parents instead of duplicating parents by the number of child matches. See nesting
distinctColumnName	No	""	When using `listDistinct=true` above, this will tell the criteria which column to group by. Typically using 'id' is a pretty safe bet.

filterPropertyValues

filterPropertyValues="${[someDateProperty:[years:2015..1999], someEnumProperty: [valueMessagePrefix: 'my.message.prefix']]}"

or get the values from the database:

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

customForm

<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>

Template

This uses

_filterpane/_filterpane.gsp
_filterpane/_filterpaneProperty.gsp
_filterpane/_filterpaneSort.gsp
_filterpane/_filterpaneButtons.gsp

6.2.5 filterLink

filterLink

This tag generates a html link that links to a filter action listing items filtered upon the specified values.

Attribute Name	Required	Default Value	Description
values	Yes	None	A map containing field values by field name. The field is the field within the bean (with the filter) that should be used for filtering. The value may contain a map with additional filter directives. See examples below.
controller	No	Current controller	The name of the controller to use in the link; if not specified the current controller will be linked.
action	No	filter	The name of the filter-action to use in the link; if not specified the action named "filter" will be linked
filterParams	No	None	Previously used filterParams can be forwarded to the link by using this attribute. Will for instance preserve sort and order if it has been currently set.
class	No	None	The class attribute to use for the html link.

Additionally you may use all the optional attributes that you can use for the grails tag g:link.

values examples

The simplest version is filtering all items by property firstName equals Adam.

values="${[firstName:'Adam']}"

Filtering all items by property firstName contains some text, requires that you specify the operator. The same applies to all the other single argument operators of the filterpane see below.

values="${[firstName:[op:'ILike', value:'Ada']]}"

Filtering all items by property firstName beginning with some text (case sensitive), requires that you specify the operator. The same applies to all the other single argument operators of the filterpane see below.

values="${[firstName:[op:'BeginsWith', value:'Ada']]}"

Filtering all items by property firstName beginning with some text (case in-sensitive), requires that you specify the operator. The same applies to all the other single argument operators of the filterpane see below.

values="${[firstName:[op:'IBeginsWith', value:'Ada']]}"

Filtering all items by property firstName ending with some text (case sensitive), requires that you specify the operator. The same applies to all the other single argument operators of the filterpane see below.

values="${[firstName:[op:'EndsWith', value:'bert']]}"

Filtering all items by property firstName ending with some text (case in-sensitive), requires that you specify the operator. The same applies to all the other single argument operators of the filterpane see below.

values="${[firstName:[op:'IEndsWith', value:'bert']]}"

Filtering all items by property age between 17 and 42.

values="${[age:[op:'Between', from:17, to:42]]}"

example usage

Creating a link that links to a filtered list of books where the author is the same as the current authorInstance:

<filterpane:filterLink values="${['author.id' : authorInstance.id]}" controller="book" action="filter">
  "Books by this author"
</filterpane:filterLink>

Available op operators

op	Description
Between	Between two values, see example above. Requires both from and to value. Both from and to values are inclusive.
Equal	Equal case insensitive
GreaterThan	Greater than
GreaterThanEquals	Greater than or equals
ILike	Contains, case insensitive
IsNotNull	No value assigned. Requires no value.
IsNull	Value is assigned. Requires no value.
LessThan	Less than
LessThanEquals	Less than or equals
Like	Like, case sensitive
NotEqual	Not equal to
NotILike	Does not contain, case insensitive.
NotLike	Does not contain, case sensitive

6.2.6 isFiltered

isFiltered

This is a logical tag that will render its body if any filters are applied.

Attribute Name	Requred	Default Value	Description
(None)

<filterpane:isFiltered>Filter Applied!</filterpane:isFiltered>

6.2.7 isNotFiltered

isNotFiltered

This is a logical tag that will render its body if no filters are applied.

Attribute Name	Requred	Default Value	Description
(None)

<filterpane:isNotFiltered>Pure and Unfiltered!</filterpane:isNotFiltered>

6.2.8 paginate

paginate

This is a convenience tag that may be used in place of the grails paginate tag. It encapsulates adding the appropriate parameters to the grails paginate tag for the developer.

Attribute Name	Required	Default Value	Description
total	Yes	None	A numeric total to be used when calculating pages. This is the same total that is passed to the Grails paginate tag.
domainBean	Yes, if total's value is null	None	If total's value is null, this tag is used to perform a count for the user and pass that to the Grails paginate tag. If not specified and total's value is null, 0 will be used as the total count.

<filterpane:paginate total="${robotCount}" domainBean="org.grails.example.nested.Robot"/>

<< 5Nested Queries

7Internationalization i18n >>

6 Reference - Reference Documentation

Table of Contents

6 Reference

Reference

6.1 Data Types

Data Types and their Available Filter Operators

Domain Constraint Modifications

6.1.1 Text

Text

6.1.2 Numeric

Numeric

6.1.3 Date

Date

6.1.4 Boolean

Boolean

6.1.5 Enum

Enum

6.1.6 Class

Class

6.2 Tags

Tags

6.2.1 includes

includes

Usage (>= 2.4.3)

Usage (>= 2.1.6)

Deprecated Usage (< 2.1.6)

6.2.2 currentCriteria

currentCriteria

filterPropertyValues

Template

6.2.3 filterButton

filterButton

Template

6.2.4 filterPane

filterPane

filterPropertyValues

customForm

Template

6.2.5 filterLink

filterLink

values examples

example usage

Available op operators

6.2.6 isFiltered

isFiltered

6.2.7 isNotFiltered

isNotFiltered

6.2.8 paginate

paginate