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">"targetPage"</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">"abort"</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">"onRequest()"</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>
}