Error, Warning and Confirmation Message API

While processing your module, if you come across an error or warning you would like to highlight to the user you can use the following functions

To show an error use the following:

  add_error("You need to enter the first name as this field is compulsory");

Additionally it is always best to provide a confirmation to the user when a submission has succeeded. For this you can us the add_confirmation function

  add_confirmation("The $name has be successfully entered into the system");

Also you can add warnings when the entry was not serious enough to cause an error, but certain actions were taken that the user should be aware of.

  add_warning("Your GPS location conflicts with your marker, and the marker has been given priority");

You can have warnings and confirmations in the same page. You can add these at any point within you module code, and the framework will buffer and output such that order of appearance is confirmation, the warning/error, and finally your module content body.

System Error Handler

Sahana contains a base error handler that traps runtime and system errors as well. This displays a “nice” message to users with information to contact the administrator and if the conf['debug'] variable is set to true will also display the technical details of the error. Thus developers should have the conf['debug'] set to true in the /conf/ file

The diagram below show a example of what is displayed when the database is not available

Displaying Outcomes Intelligently to the User

The Sahana error handler, analyses the system error and tries to guess what the root cause is. For example it translates a mysql_connect() error in laymans terms to the user as a “problem accessing the database” and gives directions to contact the administrator. If you come across errors that can be analyzed and translated please suggest it on the maindev mailing list.

Triggering System Errors

Suppose PHP does not capture a system error or error which you believe should be classified as a system error which should make your module unavailable. In this instance you can trigger a system error by using the PHP function trigger_error. Use the error type E_USER_ERROR as this is caught by the Sahana custom error handler.

if (assert($divisor == 0)) {
  trigger_error("Cannot divide by zero", E_USER_ERROR);

Stream Errors

The error display is also supported by various streams. All you have to add additional error messages into the stream is to use the standard add_error(); function as usual (for html). You can use this functionality for debugging various stream functions as well.

  add_error('error X on stream');

By default the error will be displayed using the standard error_display function, but it can be overridden by the stream's own error display function called. Here is an example of the XML stream function override

// let the XML stream have it's own error function
function shn_stream_display_error() {
    global $global;
    // return if there are no errors
    if (count($global['submit_errors']) == 0 ) return;
    echo '<errorset>';
    foreach ($global['submit_errors'] as $error){
	echo '<error>'._($error).'</error>';
    echo '</errorset>';

QR Code
QR Code dev:error (generated for current page)