Error Handling in UI Extensibility Application

Error Dialog and Locating ErrorsThrowing Own Errors

An error situation in JavaScript appears as an exception. Error may occur in M-Files core components when the application module is performing an operation, e.g. with M-Files API, or the error may be caused by JavaScript engine itself.

In both cases, if the JavaScript itself does not catch the error, the UI Extensibility Framework shows the error. If any JavaScript code was involved, the JavaScript file and line number appears in the M-Files error dialog (in Details section).

$Description: Description: C:\Users\metari\Documents\wwwpage\DevGuide_files\image011.jpg$

M-Files error dialog with JScript file in error stack

In general the error thrown out from UI operation or event handler gets reported for user, and the UI behavior is continued. In contrast, in vault operations the error situation cancels and prevents the operation.

Throwing Own Errors

The application module may throw plain-text errors for the framework. These errors are displayed with standard M-Files error dialog. The JavaScript line number is also traceable. If the error is thrown in service code, where the error dialog is not possible, the error is forwarded to Windows event log.

See the code and the error dialog below.

{

// Throw an error.

MFiles.ThrowError( "Something went wrong." );

}

$Description: Description: C:\Users\metari\Documents\wwwpage\DevGuide_files\image012.jpg$

Handling and Reporting Errors

In M-Files core the error situations can be caused either expected situation (like 'object is not checked out' style error) or internal logics error. Both situations are dealt in similar manner by M-Files, and the JavaScriptcannot know if an error thrown on core side is an expected or not. Therefore in general it is best not to catch and handle errors from M-Files core, but just let them pass through.

However if it is necessary not to let the error to escape, it can be reported right away with ICommonFunctions::ReportException method. This way both JScript and M-Files errors will be reported with standard M-Files error dialog, and the call stack is preserved for M-Files errors. See the code below.

try

{

// Code that may throw an error.

}

catch( error )

{

MFiles.ReportException( error );

}

If the program needs to get the error description for custom handling, it can use GetErrorDescription Method or GetLongErrorDescription Method to get more detailed error descriptions.