3 Usage

Usage

The plugin is typically used in an application's list pages. To use the filters, make the following changes to your page containing domain object lists or any page where filtering is required. For a full list of tags and attributes, see the Reference section later in this document.

3.1 List.gsp

Modifying your gsp

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

<asset:javascript src="fp.js"/>
<asset:stylesheet src="fp.css"/>

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. The domain is the fully qualified domain class name (domainClass.fullName)

<filterpane:filterPane domain="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.

3.2 Pagination

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: filterPaneService.filter( params, Book ),
        bookCount: filterPaneService.count( params, Book ),
        filterParams: org.grails.plugin.filterpane.FilterPaneUtils.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 tag for more info.

3.3 List Sorting

List Sorting

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

3.4 Controller

Controller

1. Inject the filter service into your controller.

def filterPaneService

2. Create the filter action in your controller.

def filter = {
    if(!params.max) params.max = 10
    render( view:'list',
        model:[ domainClassList: filterPaneService.filter( params, DomainClass ),
        domainClassCount: filterPaneService.count( params, DomainClass ),
        filterParams: org.grails.plugin.filterpane.FilterPaneUtils.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.

3.5 Joda Time

Joda Time

Joda Time 1.4 is now included with the plugin. May need to set ` legacyResolve true` in BuildConfig.groovy to inherit plugin dependencies.

The file `_dateControl.gsp` will attempt to render the joda taglib objects if using the appropriate types. You may customize this if you wish via the installed template files in your project.

Supported Types

DateTime Mapping & Support

For `DateTime` mapping support please see Joda Time Plugin Docs

It is currently not possible to do certain types of criteria query with DateTime properties mapped using PersistentDateTimeWithZone (or any other multi-column Hibernate UserType). Aggregate functions (max, min, avg, count, etc.) in projections will not work on such properties and neither will the 'between' criterion.