How to create custom error messages

In this 'how to' tutorial you will learn how you can make use of the Transaction Engine's error object when writing custom triggers (or even when adding your code to a page that uses MX Kollection 3 features) to display error messages.

As mentioned in various places in the user manual, there are two type of error messages that are handled by the Transaction Engine:

• General error messages - these are displayed on top of the page (either in development or production mode) and can address non-field specific issues as well.

• Field error messages - these are displayed below the actual field that caused the error (or the one you choose). When using a field error, you must also display a general error message.

You can call the error object from your custom code to be displayed when an error occurs. In the example code that follows, the custom code is added through a Custom Trigger (to add a Custom trigger to your page, you must have a transaction - insert, update, delete or custom - on page). A custom trigger is in fact a function, which must return something. There are only two allowed return values:

• NULL - when everything went alright.

• An instance of the tNG error object - when an error occurs.

When you want to throw a general error, first you have to create a new instance of the error object. This is done in the following manner (choose the server model that you are using):

1. PHP:
   
   $myErrorObjectName = new tNG_error("My custom error message to be displayed", array(), arrray());
    

2. ColdFusion:
   
   <cfset myErrorObjectName = Request.tNG_CreateObject("tNG_error")>
   <cfset myErrorObjectName.init("My custom error message to be displayed", Request.KT_array(), Request.KT_array())>
    

3. ASP:
   
   Set myErrorObjectName = new tNG_error
   myErrorObjectName.Init "My custom error message to be displayed", Array(), Array()
    

Next, the custom trigger must contain a way to return the newly created error object. This should be put inside the condition that determines if there is an error or not, as if it is left as the main return statement, it will always throw the error. An example trigger that throws an error follows (again, choose the example suited for your server model - the function statement is automatically added by the Custom Trigger server behavior):

1. PHP:
   
   function Trigger_custom_error_trigger(&$tNG) {
   if (error_condition) {
    $myErrorObjectName = new NG_error("My custom error message to be displayed", array(), arrray());
   return $myErrorObjectName;
   } else {
   return null;
   }
   }
    

2. ColdFusion:
   
   function Trigger_Custom(tNG) {
   if (error_condition) {
   myErrorObjectName = Request.tNG_CreateObject("tNG_error");
   myErrorObjectName.init("My custom error message to be displayed", Request.KT_array(), Request.KT_array());
   return myErrorObjectName;
   }
   return Request.KT_Null;
   }
    

3. ASP:
   
   Function Trigger_Custom (ByRef tNG)
   if(error_condition)  then
   Set myErrorObjectName = new tNG_error
   myErrorObjectName.Init "The custom error message", Array(), Array()
   Set Trigger_Custom = myErrorObjectName
   else
   Set Trigger_Custom =Nothing
   End if
   End Function
    

The code bits above are used in custom triggers to return a general error (the myErrorObjectName error object). To also display a field error, there is a single line that must be added after the error object has been initialized. Below is an example (when using it, remember to replace the parts that are descriptive - eg. my_field_name, Trigger_custom, etc - by the actual values that you are using - the actual field where to display the error, the actual trigger name etc -). Choose the one that fits your particular server model:

1. PHP:
   
   $myErrorObjectName->setFieldError("my_field_name", "My field error message to display.", array());
    

2. ColdFusion: if not entering the code inside a <cfscript> tag, you must use <cfset> tags.
   
   myErrorObjectName.setFieldError("my_field_name", "My field error message to display.", Request.KT_array())
    

3. ASP:
   
   myErrorObjectName.setFieldError "my_field_name", "My field error message to display", array()