<b>Tag:</b> triggers
<span class="since">since 1.4</span>

Defines a list of triggers to activate on some Ivy events.

A trigger is an action which is performed whenever a particular event occurs.
Ivy supports two type of triggers out of the box: ant-call and ant-build. The first calls a target in the same build as the original one whenever a particular event occurs, the second call an ant build which may be in another ant build script.

If you want to use a different trigger, you can <a href="../extend.html">implement your own</a>.

The event available in Ivy are the following ones:
<table class="ivy-children">
<thead>
    <tr><th>Name</th><th>Attributes</th><th>Description</th></tr>
</thead>
<tbody>
    <tr><td>pre-resolve</td>
        <td>
          <ul>
            <li>organisation</li>the organisation of the module for which the dependencies will be resolved
            <li>module</li>the name of the module for which the dependencies will be resolved
            <li>revision</li>the revision of the module for which the dependencies will be resolved
            <li>conf</li>comma separated list of configurations which will be resolved
          </ul>
        </td>
        <td>Fired before a module dependencies will be resolved</td>
    </tr>
    <tr><td>pre-resolve-dependency</td>
        <td>
          <ul>
            <li>organisation</li>the organisation of the dependency resolved
            <li>module</li>the name of the dependency resolved
            <li>revision</li>the revision asked for the dependency
            <li>resolver</li>the name of the resolver used to resolve the dependency
          </ul>
        </td>
        <td>Fired before each dependency is resolved in a single resolve call</td>
    </tr>
    <tr><td>post-resolve-dependency</td>
        <td>
          <ul>
            <li>organisation</li>the organisation of the dependency resolved
            <li>module</li>the name of the dependency resolved
            <li>revision</li>the revision of the dependency resolved, or the revision asked if the resolution was not successful
            <li>resolved</li>true if the resolution was successful, false otherwise
            <li>resolver</li>the name of the resolver used to resolve the dependency
          </ul>
        </td>
        <td>Fired after each dependency resolved in a single resolve call</td>
    </tr>
    <tr><td>post-resolve</td>
        <td>
          <ul>
            <li>organisation</li>the organisation of the module for which the dependencies have been resolved
            <li>module</li>the name of the module for which the dependencies have been resolved
            <li>revision</li>the revision of the module for which the dependencies have been resolved
            <li>conf</li>comma separated list of configurations resolved
          </ul>
        </td>
        <td>Fired after a module dependencies has been resolved</td>
    </tr>
    <tr><td>pre-download-artifact</td>
        <td>
          <ul>
            <li>organisation</li>the organisation of the artifact which is about to be downloaded
            <li>module</li>the name of the module of the artifact which is about to be downloaded
            <li>revision</li>the revision of the the artifact which is about to be downloaded
            <li>artifact</li>the name of the the artifact which is about to be downloaded
            <li>type</li>the type of the the artifact which is about to be downloaded
            <li>ext</li>the extension of the the artifact which is about to be downloaded
            <li>resolver</li>the name of the resolver used to download the artifact
            <li>origin</li>the origin location from which it will be downloaded
            <li>local</li>true if it's a local artifact, false otherwise
          </ul>
        </td>
        <td>Fired before an artifact is downloaded from a repository to the cache</td>
    </tr>
    <tr><td>post-download-artifact</td>
        <td>
          <ul>
            <li>organisation</li>the organisation of the artifact which was just downloaded
            <li>module</li>the name of the module of the artifact which was just downloaded
            <li>revision</li>the revision of the the artifact which was just downloaded
            <li>artifact</li>the name of the the artifact which was just downloaded
            <li>type</li>the type of the the artifact which was just downloaded
            <li>ext</li>the extension of the the artifact which was just downloaded
            <li>resolver</li>the name of the resolver used to download the artifact
            <li>origin</li>the origin location from which it was downloaded
            <li>local</li>true if it's a local artifact, false otherwise
            <li>size</li>the size in bytes of the downloaded artifact
            <li>file</li>the file to which it has been downloaded
          </ul>
        </td>
        <td>Fired after an artifact has been downloaded from a repository to the cache</td>
    </tr>
</tbody>
</table>

The child tag used for the dependency resolver must be equal to a name of a trigger type (either built-in or added with the typedef tag).

<h1>Child elements</h1>
<table class="ivy-children">
<thead>
    <tr><th class="ivy-chld">Element</th><th class="ivy-chld-desc">Description</th><th class="ivy-chld-card">Cardinality</th></tr>
</thead>
<tbody>
    <tr><td>any trigger</td><td>adds a trigger to the list of registered triggers</td>
        <td>1..n</td></tr>
</tbody>
</table>

<h1>Built-in Triggers</h1>
Ivy comes with two built-in triggers:

<table class="ivy-attributes">
<thead>
    <tr><th>Name</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td>ant-build</td><td>Triggers an ant build.</td></tr>
<tr><td>ant-call</td><td>Calls a target in the current ant build.</td></tr>
</tbody>
</table>

<h1><a name="common">Common attributes</a></h1>
All triggers share some common attributes detailed here.

Among these attributes, you will find how to select when the trigger should be performed. You have to provide an event name, which is simple, but you can also use a filter expression. The syntax for this expression is very simple and limited: 
you can use the = operator to compare an attribute (left operande) with a value (right operande).
you can use AND OR NOT as boolean operators
you cannot use parenthesis to change the precedence

<table class="ivy-attributes">
<thead>
    <tr><th class="ivy-att">Attribute</th><th class="ivy-att-desc">Description</th><th class="ivy-att-req">Required</th></tr>
</thead>
<tbody>
    <tr><td>name</td><td>the name of the trigger for identification purpose only</td>
        <td>Yes</td>
    </tr>
    <tr><td>event</td><td>the name of the event on which the trigger should be performed</td>
        <td>Yes</td>
    </tr>
    <tr><td>filter</td><td>a filter expression used to restrict when the trigger should be performed</td>
        <td>No, defaults to no filter</td>
    </tr>
</tbody>
</table>

<h1>Examples</h1>
<code type="xml">
<triggers>
    <ant-build antfile="${ivy.settings.dir}/[module]/build.xml" target="publish"
           event="pre-resolve-dependency" filter="revision=latest.integration"/>
</triggers>
</code>
Triggers an ant build of the ant file ${ivy.settings.dir}/[module]/build.xml (where [module] is replaced by the name of the dependency resolved) with the target "publish", just before resolving a dependency with a latest.integration revision.
<hr/>
<code type="xml">
<triggers>
    <ant-call target="unzip" prefix="dep"
          event="post-download-artifact" filter="type=zip AND status=successful"/>
</triggers>
</code>
Triggers an ant call of the target unzip just after downloading a zip artifact, prefixing all parameters to the target with 'dep'.
Here is how the target can look like:
<code type="xml">
<target name="unzip">
     <echo>
        unzipping artifact: 
        organisation=${dep.organisation} 
        module=${dep.module} 
        revision=${dep.revision}
        artifact=${dep.artifact}
        type=${dep.type}
        ext=${dep.ext}
        origin=${dep.origin}
        local=${dep.local}
        size=${dep.size}
        file=${dep.file}
     </echo>
     <mkdir dir="${basedir}/out"/>
     <unzip src="${dep.file}" dest="${basedir}/out"/>
</target>
</code>