nui_error_handler 0.0.14

A new Flutter package for error handling

---

id: flutter-sdk-nuierrorhandler title: NUIErrorHandler Overview sidebar_label: Overview

NUIErrorHandler is a Flutter package that tracks the errors/exceptions happening around the app and carry out an action in return according to a pre-defined mapping. This way when an exception or error is encountered, this framework can guide the user to the next step.

• Pre-defined Error/Action Mapping - Specify the list of errors and the action to be taken when this error occurred in the app. The actions can be a Toast, a pop-up or even a screen redirect.

• Manual Trigger - Prompt an action with just an error code that is pre-defined in the mapping anywhere in the app. This allows the NUIErrorHandler framework to be usable in different layer of the app (Network, Data, Logic).

• Error Logging - All the exceptions encountered in the app that is not caught will be tracked and saved into the phone's database. They can then be used to trace back the list of exceptions that has been encountered.

• Instant Exception Debugging - Configure the framework to display the exception's details whenever one is encountered to make it easier for debugging.

Builder Method for NUIErrorHandler

Method	Remark
module()	Specify the module of this NUIErrorHandler instance
appVersion()	Specify app version for more accurate error tracing
mappingURL()	Specify the url to download the excel mapping file
redirect()	Implement redirect according to the actions in mapping
popUp()	Implement a custom pop-up dialog for the error
build()	Build the NUIErrorHandler instance with the builder.

Initialize NUIErrorHandler with NUIErrorHandlerBuilder.

Create a NUIErrorHandler instance to build NUIErrorHandler instance.

var errorHandler = NUIErrorHandlerBuilder();

Specifying the module.

On the builder method, users can specify the module of the NUIErrorHandler instance to have multiple NUIErrorHandler instance for the app.

builder.module("hintv2");

Specifying the app version.

On the builder method, users can specify the current app version to better trace the errors/exceptions that are going on in the app.

builder.appVersion("1.1.8");

Specifying the mapping URL.

On the builder method, users can specify the mapping URL to download and get the excel file with the error mappings.

builder.mappingUrl("https://hintv2/errormapping/mapping.xls");

Specifying the redirect actions.

On the builder method, users can specify redirect actions according to the action code and action type in the error mappings.

builder.redirect((context, actionCode, errorMapping) { 
    switch(actionCode){
      case "404": {
        //Todo something here 
        break;
      }
    }       
});

Adding a custom pop-up.

Users can add a custom pop-up for a personalized UI look and feel or use the default pop-up by the framework.

builder.popUp((context, errorMapping) {
    showDialog(context: context, builder: (context){
      return Container(
        child: Text(errorMapping.message),
      );
    });
})

Build the NUIErrorHandler instance

Once all the customizations for this NUIErrorHandler is done, building the instance with NUIErrorHandlerBuilder will return the instance of the NUIErrorHandler.

final errorHandler = builder.build();

A Complete Example for Building A NUIErrorHandler Instance

final errorHandler = NUIErrorHandlerBuilder()
          .module("app")
          .appVersion("1.0.1")
          .mappingURL("url")
          .redirect((context, actionCode, errorMapping) {
              switch(actionCode){
                case "404": {
                  //Todo something here
                  break;
                }
              }
            })
          .popUp((context, errorMapping) {
            showDialog(context: context, builder: (context){
              return Container(
                child: Text(errorMapping.message),
              );
            });
          });

Integrating NUIErrorHandler to the NUICore framework.

runNUIAppWithExceptionHandler();

Available Methods for NUIErrorHandler

Method	Remark
get()	Get the instance of the built NUIErrorHandler instance
saveErrorLog()	Save an error log into the phone database
saveErrorByException()	Save an error log from an exception encountered
showLastErrorLog()	Show the detail of the last encountered error
showErrorLogDetail()	Show the detail of a specified error log
showErrorLogs()	Show the last 50 errors encountered in the app
getErrorLogs()	Get the list of error logs in the app
getLastErrorLog()	Get the last error log encountered
processError()	Process an error that is pre-defined in the mapping

Error Mapping Action Types

Value	Remark
Log	Log the error encountered
Toast	Show a toast message for the error
Pop-Up	Show a pop-up dialog for the error
Redirect	Redirect to another screen based on the action code

Getting the NUIErrorHandler Instance

Users get the built NUIErrorHandler instance for the targeted module.

final errorHandler = NUIErrorHandler.get(module: "hintv2");

Saving an Error Log

• Parameters:

  Name	Type	Nullable	Remark
  log	NUIErrorLog	N	The error log with its details

Example of a Saving an Error Log

NUIErrorLog log = NUIErrorLog(
          id: randomUUID(),
          type: NUIErrorType.CRASH.value(),
          title: title,
          description: description,
          appVersion: "1.0.9",
          dateTime: DateTime.now(),
          module: "hintv2",
          code: deviceInfo.version,
          platform: deviceInfo.platform,
          model: deviceInfo.model,
          screenCode: screenCode
      );
      return saveErrorLog(log);

Saving an Error by Exception

• Parameters:

  Name	Type	Nullable	Remark
  error	Object	N	The error object, could be the title of the exception
  stackTrace	StackTrace	N	The stacktrace from an exception
  screenCode	String	Y	The screen code that represents the current screen displayed

Example of Saving an Error by Exception

final saveError = await NUIErrorHandler.get().saveErrorByException(error, stackTrace, screenCode: "Login Screen");

Showing the Last Error Log

• Parameters:

  Name	Type	Nullable	Remark
  context	BuildContext	N	The context to inflate the error log details UI

Example of Showing the Last Error Log

NUIErrorHandler().get().showLastErrorLog(context);

Showing Details of an Error Log

• Parameters:

  Name	Type	Nullable	Remark
  context	BuildContext	N	The context to inflate the error log details UI
  log	NUIErrorLog	N	The error log for the details

Example of Showing the Details of an Error Log

NUIErrorHandler().get().showErrorLogDetail(context, log);

Showing the List of Error Logs

• Parameters:

  Name	Type	Nullable	Remark
  context	BuildContext	N	The context to inflate the error log details UI

Example of Showing the List of Error Logs

NUIErrorHandler().get().showErrorLogs(context);

Get the Error Logs

NUIErrorHandler().get().getErrorLogs();

Get the Last Error Log

NUIErrorHandler().get().getLastErrorLog();

Process an Error

• Parameters:

  Name	Type	Nullable	Remark
  context	BuildContext	N	The context to inflate the error log details UI
  code	String	N	The error log for the details

Example of Processing an Error

NUIErrorHandler().get().processError(context, "404");