(Quick Reference)

7.6.1 Applying Filters - Reference Documentation

Authors: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith, Lari Hotari

Version: 2.3.8

7.6.1 Applying Filters

To create a filter create a class that ends with the convention Filters in the grails-app/conf directory. Within this class define a code block called filters that contains the filter definitions:

class ExampleFilters {
   def filters = {
        // your filters here
   }
}

Each filter you define within the filters block has a name and a scope. The name is the method name and the scope is defined using named arguments. For example to define a filter that applies to all controllers and all actions you can use wildcards:

sampleFilter(controller:'*', action:'*') {
  // interceptor definitions
}

The scope of the filter can be one of the following things:

  • A controller and/or action name pairing with optional wildcards
  • A URI, with Ant path matching syntax

Filter rule attributes:

  • controller - controller matching pattern, by default * is replaced with .* and a regex is compiled
  • controllerExclude - controller exclusion pattern, by default * is replaced with .* and a regex is compiled
  • action - action matching pattern, by default * is replaced with .* and a regex is compiled
  • actionExclude - action exclusion pattern, by default * is replaced with .* and a regex is compiled
  • regex (true/false) - use regex syntax (don't replace '*' with '.*')
  • uri - a uri to match, expressed with as Ant style path (e.g. /book/**)
  • uriExclude - a uri pattern to exclude, expressed with as Ant style path (e.g. /book/**)
  • find (true/false) - rule matches with partial match (see java.util.regex.Matcher.find())
  • invert (true/false) - invert the rule (NOT rule)

Some examples of filters include:

  • All controllers and actions

all(controller: '*', action: '*') {

}

  • Only for the BookController

justBook(controller: 'book', action: '*') {

}

  • All controllers except the BookController

notBook(controller: 'book', invert: true) {

}

  • All actions containing 'save' in the action name

saveInActionName(action: '*save*', find: true) {

}

  • All actions starting with the letter 'b' except for actions beginning with the phrase 'bad*'

actionBeginningWithBButNotBad(action: 'b*', actionExclude: 'bad*', find: true) {

}

  • Applied to a URI space

someURIs(uri: '/book/**') {

}

  • Applied to all URIs

allURIs(uri: '/**') {

}

In addition, the order in which you define the filters within the filters code block dictates the order in which they are executed. To control the order of execution between Filters classes, you can use the dependsOn property discussed in filter dependencies section.

Note: When exclude patterns are used they take precedence over the matching patterns. For example, if action is 'b*' and actionExclude is 'bad*' then actions like 'best' and 'bien' will have that filter applied but actions like 'bad' and 'badlands' will not.