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.

It's recommend not to leave empty placeholder functions for any of these functions, unless you are using them.

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.

It's recommended to avoid creating sessions unless required, especially on public pages, given all the bots around these days.

You can test if a session has been created using SessionExists(), because calling function-structKeyExist on the session scope will create a session if it doesn't exist.

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

OnSessionEnd

This method is triggered when a session expires.

If you don't need this functionality, don't use it, it does add overhead as the session application settings are persisted with the session to be available when the session expires.

component {
   void function onSessionEnd() {
       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", this function is used to pre process remote <cfcomponent> function 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 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 {

    /**
    * @hint onApplicationStart() is triggered when the application starts.
    */
    public boolean function onApplicationStart(){

        return true;

    }


    /**
    * @hint onSessionStart() is triggered when a session starts.
    */
    public boolean function onSessionStart(){

        return true;

    }


    /**
    * @hint onRequestStart() is triggered at the start of each request.
    */
    public boolean function onRequestStart(string targetPage){

        return true;

    }


    /**
    * @hint onRequest() is triggered during a request right after onRequestStart() ends and before onRequestEnd() starts. Unlike other CFML engines, Lucee executes this function without looking for the "targetPage" defined, while other CFML engines will complain if the targetPage doesn’t physically exist (even if not used in the onRequest() function).
    */
    public void function onRequest(string targetPage){

        include arguments.targetPage;
        return;

    }


    /**
    * @hint onRequestEnd() is triggered at the end of a request, right after onRequest() finishes.
    */
    public void function onRequestEnd(){

        return;

    }


    /**
    * @hint onCFCRequest() is triggered during a request for a .cfc component, typically used to handle remote component calls (e.g. HTTP Webservices).
    */
    public void function onCFCRequest(string cfcName, string methodName, struct args){

        return;

    }


    /**
    * @hint onError() is triggered when an uncaught exception occurs in this application context.
    */
    public void function onError(struct exception, string eventName){

        return;

    }


    /**
    * @hint OnAbort() is triggered when a request is ended with help of the "abort" tag.
    */
    public void function onAbort(string targetPage){

        return;

    }


    /**
    * @hint onDebug() is triggered when debugging is enabled for this request.
    */
    public void function onDebug(struct debuggingData){

        return;

    }


    /**
    * @hint onMissingTemplate() is triggered when the requested page wasn’t found and no "onRequest()" function is defined.
    */
    public void function onMissingTemplate(string targetPage){

        return;

    }

}

See also