Event Handling in Application.cfc

Event Handling in Application.cfc

Lucee provides several event handling functions within Application.cfc that can be used to manage different stages and types of requests. Here is an overview of these functions and their usage.

OnApplicationStart

This method is triggered when the application starts.

component {
   void function onApplicationStart() {
       echo('Application started');
   }
}

OnSessionStart

This method is triggered when a session starts.

component {
   void function onSessionStart() {
       echo('Session started');
   }
}

OnRequestStart

This method is triggered at the start of each request.

component {
   void function onRequestStart(string targetPage) {
       echo('Request started: ' & targetPage);
   }
}

OnRequest

This method handles the actual request. In Lucee, this function is called even if the target page does not exist physically or is never used.

component {
   void function onRequest(string targetPage) {
       echo('<html><body>Hello World</body></html>');
   }
}

OnCFCRequest

Similar to "onRequest", but this function is used to handle remote component calls (HTTP Webservices).

component {
   void function onCFCRequest(string cfcName, string methodName, struct args) {
       echo('<html><body>Hello World</body></html>');
   }
}

OnError

This method is triggered when an uncaught exception occurs in this application context.

component {
   void function onError(struct exception, string eventName) {
       dump(var:exception, label:eventName);
   }
}

As arguments you receive the exception (cfcatch block) and the eventName.

OnAbort

This method is triggered when a request is ended with help of the tag <cfabort>.

component {
   void function onAbort(string targetPage) {
       dump('request ' & targetPage & ' ended with an abort!');
   }
}

OnDebug

This method is triggered when debugging is enabled for this request.

component {
   void function onDebug(struct debuggingData) {
       dump(var:debuggingData, label:'debug information');
   }
}

OnMissingTemplate

This method is triggered when a requested page was not found and no function "onRequest" is defined.

component {
   void function onMissingTemplate(string targetPage) {
       echo('missing:' & targetPage);
   }
}

Application.cfc Default Template

Below you can find an Application.cfc template that may serve as a starting point for your own applications settings with Lucee CFML engine.

When creating an Application.cfc for the first time, you can configure all the settings within the Lucee Server or Web Administrator and use its "Export" tool (Lucee Administrator => Settings => Export) to move (by copy and paste) the settings into your Application.cfc file.

component {

<span class="o">/**</span>
<span class="o">*</span> <span class="err">@</span><span class="nv">hint</span> <span class="nf">onApplicationStart</span><span class="p">()</span> <span class="o">is</span> <span class="nv">triggered</span> <span class="nv">when</span> <span class="nv">the</span> <span class="nv">application</span> <span class="nv">starts.</span>
<span class="o">*/</span>
<span class="nv">public</span> <span class="nv">boolean</span> <span class="nv">function</span> <span class="nf">onApplicationStart</span><span class="p">(){</span>
    <span class="nv">return</span> <span class="nv">true</span><span class="p">;</span>
<span class="p">}</span>
<span class="o">/**</span>
<span class="o">*</span> <span class="err">@</span><span class="nv">hint</span> <span class="nf">onSessionStart</span><span class="p">()</span> <span class="o">is</span> <span class="nv">triggered</span> <span class="nv">when</span> <span class="nv">a</span> <span class="nv">session</span> <span class="nv">starts.</span>
<span class="o">*/</span>
<span class="nv">public</span> <span class="nv">boolean</span> <span class="nv">function</span> <span class="nf">onSessionStart</span><span class="p">(){</span>
    <span class="nv">return</span> <span class="nv">true</span><span class="p">;</span>
<span class="p">}</span>
<span class="o">/**</span>
<span class="o">*</span> <span class="err">@</span><span class="nv">hint</span> <span class="nf">onRequestStart</span><span class="p">()</span> <span class="o">is</span> <span class="nv">triggered</span> <span class="nv">at</span> <span class="nv">the</span> <span class="nv">start</span> <span class="nv">of</span> <span class="nv">each</span> <span class="nv">request.</span>
<span class="o">*/</span>
<span class="nv">public</span> <span class="nv">boolean</span> <span class="nv">function</span> <span class="nf">onRequestStart</span><span class="p">(</span><span class="nv">string</span> <span class="nv">targetPage</span><span class="p">){</span>
    <span class="nv">return</span> <span class="nv">true</span><span class="p">;</span>
<span class="p">}</span>
<span class="o">/**</span>
<span class="o">*</span> <span class="err">@</span><span class="nv">hint</span> <span class="nf">onRequest</span><span class="p">()</span> <span class="o">is</span> <span class="nv">triggered</span> <span class="nv">during</span> <span class="nv">a</span> <span class="nv">request</span> <span class="nv">right</span> <span class="nv">after</span> <span class="nf">onRequestStart</span><span class="p">()</span> <span class="nv">ends</span> <span class="o">and</span> <span class="nv">before</span> <span class="nf">onRequestEnd</span><span class="p">()</span> <span class="nv">starts.</span> <span class="nv">Unlike</span> <span class="nv">other</span> <span class="nv">CFML</span> <span class="nv">engines</span><span class="p">,</span> <span class="nv">Lucee</span> <span class="nv">executes</span> <span class="nv">this</span> <span class="nv">function</span> <span class="nv">without</span> <span class="nv">looking</span> <span class="nv">for</span> <span class="nv">the</span> <span class="s2">&quot;targetPage&quot;</span> <span class="nv">defined</span><span class="p">,</span> <span class="nv">while</span> <span class="nv">other</span> <span class="nv">CFML</span> <span class="nv">engines</span> <span class="nv">will</span> <span class="nv">complain</span> <span class="k">if</span> <span class="nv">the</span> <span class="nv">targetPage</span> <span class="nv">doesn</span><span class="err">’</span><span class="nv">t</span> <span class="nv">physically</span> <span class="nf">exist</span> <span class="p">(</span><span class="nv">even</span> <span class="k">if</span> <span class="o">not</span> <span class="nv">used</span> <span class="nv">in</span> <span class="nv">the</span> <span class="nf">onRequest</span><span class="p">()</span> <span class="nv">function</span><span class="p">).</span>
<span class="o">*/</span>
<span class="nv">public</span> <span class="nv">void</span> <span class="nv">function</span> <span class="nf">onRequest</span><span class="p">(</span><span class="nv">string</span> <span class="nv">targetPage</span><span class="p">){</span>
    <span class="nv">include</span> <span class="nv">arguments.targetPage</span><span class="p">;</span>
    <span class="nv">return</span><span class="p">;</span>
<span class="p">}</span>
<span class="o">/**</span>
<span class="o">*</span> <span class="err">@</span><span class="nv">hint</span> <span class="nf">onRequestEnd</span><span class="p">()</span> <span class="o">is</span> <span class="nv">triggered</span> <span class="nv">at</span> <span class="nv">the</span> <span class="nv">end</span> <span class="nv">of</span> <span class="nv">a</span> <span class="nv">request</span><span class="p">,</span> <span class="nv">right</span> <span class="nv">after</span> <span class="nf">onRequest</span><span class="p">()</span> <span class="nv">finishes.</span>
<span class="o">*/</span>
<span class="nv">public</span> <span class="nv">void</span> <span class="nv">function</span> <span class="nf">onRequestEnd</span><span class="p">(){</span>
    <span class="nv">return</span><span class="p">;</span>
<span class="p">}</span>
<span class="o">/**</span>
<span class="o">*</span> <span class="err">@</span><span class="nv">hint</span> <span class="nf">onCFCRequest</span><span class="p">()</span> <span class="o">is</span> <span class="nv">triggered</span> <span class="nv">during</span> <span class="nv">a</span> <span class="nv">request</span> <span class="nv">for</span> <span class="nv">a</span> <span class="p">.</span><span class="nv">cfc</span> <span class="nv">component</span><span class="p">,</span> <span class="nv">typically</span> <span class="nv">used</span> <span class="nv">to</span> <span class="nv">handle</span> <span class="nv">remote</span> <span class="nv">component</span> <span class="nf">calls</span> <span class="p">(</span><span class="nv">e.g.</span> <span class="nv">HTTP</span> <span class="nv">Webservices</span><span class="p">).</span>
<span class="o">*/</span>
<span class="nv">public</span> <span class="nv">void</span> <span class="nv">function</span> <span class="nf">onCFCRequest</span><span class="p">(</span><span class="nv">string</span> <span class="nv">cfcName</span><span class="p">,</span> <span class="nv">string</span> <span class="nv">methodName</span><span class="p">,</span> <span class="nv">struct</span> <span class="nv">args</span><span class="p">){</span>
    <span class="nv">return</span><span class="p">;</span>
<span class="p">}</span>
<span class="o">/**</span>
<span class="o">*</span> <span class="err">@</span><span class="nv">hint</span> <span class="nf">onError</span><span class="p">()</span> <span class="o">is</span> <span class="nv">triggered</span> <span class="nv">when</span> <span class="nv">an</span> <span class="nv">uncaught</span> <span class="nv">exception</span> <span class="nv">occurs</span> <span class="nv">in</span> <span class="nv">this</span> <span class="nv">application</span> <span class="nv">context.</span>
<span class="o">*/</span>
<span class="nv">public</span> <span class="nv">void</span> <span class="nv">function</span> <span class="nf">onError</span><span class="p">(</span><span class="nv">struct</span> <span class="nv">exception</span><span class="p">,</span> <span class="nv">string</span> <span class="nv">eventName</span><span class="p">){</span>
    <span class="nv">return</span><span class="p">;</span>
<span class="p">}</span>
<span class="o">/**</span>
<span class="o">*</span> <span class="err">@</span><span class="nv">hint</span> <span class="nf">OnAbort</span><span class="p">()</span> <span class="o">is</span> <span class="nv">triggered</span> <span class="nv">when</span> <span class="nv">a</span> <span class="nv">request</span> <span class="o">is</span> <span class="nv">ended</span> <span class="nv">with</span> <span class="nv">help</span> <span class="nv">of</span> <span class="nv">the</span> <span class="s2">&quot;abort&quot;</span> <span class="nv">tag.</span>
<span class="o">*/</span>
<span class="nv">public</span> <span class="nv">void</span> <span class="nv">function</span> <span class="nf">onAbort</span><span class="p">(</span><span class="nv">string</span> <span class="nv">targetPage</span><span class="p">){</span>
    <span class="nv">return</span><span class="p">;</span>
<span class="p">}</span>
<span class="o">/**</span>
<span class="o">*</span> <span class="err">@</span><span class="nv">hint</span> <span class="nf">onDebug</span><span class="p">()</span> <span class="o">is</span> <span class="nv">triggered</span> <span class="nv">when</span> <span class="nv">debugging</span> <span class="o">is</span> <span class="nv">enabled</span> <span class="nv">for</span> <span class="nv">this</span> <span class="nv">request.</span>
<span class="o">*/</span>
<span class="nv">public</span> <span class="nv">void</span> <span class="nv">function</span> <span class="nf">onDebug</span><span class="p">(</span><span class="nv">struct</span> <span class="nv">debuggingData</span><span class="p">){</span>
    <span class="nv">return</span><span class="p">;</span>
<span class="p">}</span>
<span class="o">/**</span>
<span class="o">*</span> <span class="err">@</span><span class="nv">hint</span> <span class="nf">onMissingTemplate</span><span class="p">()</span> <span class="o">is</span> <span class="nv">triggered</span> <span class="nv">when</span> <span class="nv">the</span> <span class="nv">requested</span> <span class="nv">page</span> <span class="nv">wasn</span><span class="err">’</span><span class="nv">t</span> <span class="nv">found</span> <span class="o">and</span> <span class="nv">no</span> <span class="s2">&quot;onRequest()&quot;</span> <span class="nv">function</span> <span class="o">is</span> <span class="nv">defined.</span>
<span class="o">*/</span>
<span class="nv">public</span> <span class="nv">void</span> <span class="nv">function</span> <span class="nf">onMissingTemplate</span><span class="p">(</span><span class="nv">string</span> <span class="nv">targetPage</span><span class="p">){</span>
    <span class="nv">return</span><span class="p">;</span>
<span class="p">}</span>



}

See also