## 4.3 Hooking into Events

Grails provides the ability to hook into scripting events. These are events triggered during execution of Grails target and plugin scripts.

The mechanism is deliberately simple and loosely specified. The list of possible events is not fixed in any way, so it is possible to hook into events triggered by plugin scripts, for which there is no equivalent event in the core target scripts.

#### Defining event handlers

Event handlers are defined in scripts called `_Events.groovy`. Grails searches for these scripts in the following locations:

- `USER_HOME/.grails/scripts` - user-specific event handlers
- `PROJECT_HOME/scripts` - applicaton-specific event handlers
- `PLUGINS_HOME/*/scripts` - plugin-specific event handlers
- `GLOBAL_PLUGINS_HOME/*/scripts` - event handlers provided by global plugins

Whenever an event is fired, all the registered handlers for that event are executed. Note that the registration of handlers is performed automatically by Grails, so you just need to declare them in the relevant `_Events.groovy` file.

> In versions of Grails prior to 1.0.4, the script was called `Events.groovy`, that is without the leading underscore.

Event handlers are blocks defined in `_Events.groovy`, with a name beginning with "event". The following example can be put in your /scripts directory to demonstrate the feature:

    eventCreatedArtefact = { type, name ->
       println "Created $type $name"
    }eventStatusUpdate = { msg ->
       println msg
    }eventStatusFinal = { msg ->
       println msg
    }

You can see here the three handlers `eventCreatedArtefact`, `eventStatusUpdate`, `eventStatusFinal`. Grails provides some standard events, which are documented in the command line reference guide. For example the compile command fires the following events:

- `CompileStart` - Called when compilation starts, passing the kind of compile - source or tests
- `CompileEnd` - Called when compilation is finished, passing the kind of compile - source or tests

#### Triggering events

To trigger an event simply include the Init.groovy script and call the event() closure:

    includeTargets << grailsScript("_GrailsEvents")event("StatusFinal", ["Super duper plugin action complete!"])

#### Common Events

Below is a table of some of the common events that can be leveraged:

Event | Parameters | Description
--- | --- | ---
StatusUpdate | message | Passed a string indicating current script status/progress
StatusError | message | Passed a string indicating an error message from the current script
StatusFinal | message | Passed a string indicating the final script status message, i.e. when completing a target, even if the target does not exit the scripting environment
CreatedArtefact | artefactType,artefactName | Called when a create-xxxx script has completed and created an artefact
CreatedFile | fileName | Called whenever a project source filed is created, not including files constantly managed by Grails
Exiting | returnCode | Called when the scripting environment is about to exit cleanly
PluginInstalled | pluginName | Called after a plugin has been installed
CompileStart | kind | Called when compilation starts, passing the kind of compile - source or tests
CompileEnd | kind | Called when compilation is finished, passing the kind of compile - source or tests
DocStart | kind | Called when documentation generation is about to start - javadoc or groovydoc
DocEnd | kind | Called when documentation generation has ended - javadoc or groovydoc
SetClasspath | rootLoader | Called during classpath initialization so plugins can augment the classpath with rootLoader.addURL(...). Note that this augments the classpath after event scripts are loaded so you cannot use this to load a class that your event script needs to import, although you can do this if you load the class by name.
PackagingEnd | none | Called at the end of packaging (which is called prior to the Tomcat server being started and after web.xml is generated)