STIErrorHandling

STIErrorHandling is a small Framework that provides a base implementation for error handling in iOS applications. It deals with the problem to streamline the presentation of errors in various parts of an application as well as provide APIs to implement error specific recovery options the user of the application can choose from.

The presentation of an error is reduced to a single line of code that can be called from any view, view controller or any other class that inherits from UIResponder:

[self presentError:error completionHandler:^(BOOL didRecover) {
	if (didRecover) {
   		[self tryAgain];
	}
}];

This is all the code you need to implement in your view controllers if an operation that returns an NSError fails.

Requirements

This project requires nothing more than the Foundation and UIKit frameworks.

Usage

To run the example project, clone the repo, and run pod install from the Example directory first.

The example project shows a simple save operation that fails if the file in question already exists. The error handling asks you if you want to overwrite the file or not. If any other error occurs, a default error message is generated instead.

Presenting an error

To present an error in your application you can call the following method in every instance of UIView, UIViewController or any other class that inherits from UIResponder to show a UIAlertController that represents the error:

-[UIResponder presentError:completionHandler:]

You pass the NSError object you received as the first argument to this method. The second argument is a completion block that gets called once the user taps one of the options from the alert view and the error recovery attempt finished executing. The completion handler takes one argument, a BOOL that reports to you, whether error recovery was successful. If the recovery was successful it is save to try the same operation that previously lead to the error again and you should always do so.

Creating an error

To create an error you need to provide a couple of informations the alert view will use to present and recover from the error. A basic error creation looks like this:

STIErrorRecoveryAttempter *attempter = [STIErrorRecoveryAttempter new];
[attempter addOkayRecoveryOption];

NSString *localizedFailureReason = @"No internet connection";
NSString *localizedRecoverySuggestion = @"Sorry, it seems like your device currently does not have access to the internet. Please try again later or check your network settings.";

NSDictionary *userInfo = @{
						   NSLocalizedFailureReasonErrorKey: localizedFailureReason,
						   NSLocalizedRecoverySuggestionErrorKey: localizedRecoverySuggestion,
						   NSLocalizedRecoveryOptionsErrorKey: attempter.localizedRecoveryOptions,
						   NSRecoveryAttempterErrorKey: attempter
					   };

NSError *error = [NSError errorWithDomain:MyErrorDomain code:MyErrorCode userInfo:userInfo];

When passing this error to -[UIResponder presentError:completionHandler:] it will create an alert view with the title that is stored in NSLocalizedFailureReasonErrorKey and the message stored in NSLocalizedRecoverySuggestionErrorKey. The alert view has only one button, labeled 'OK'. No recovery is done. This is the minimum information that is needed to present an error to the user.

To add recovery options, you call addRecoveryOptionWithTitle:recoveryAttempt: on the STIErrorRecoveryAttempter once for every recovery option you want to add. It takes the localized title of the button and a block that contains the action that should be triggered if the user chooses this recovery option. The block returns a BOOL that describes whether error recovery was successful or not. Please note that you should always add at least one recovery option that returns NO. This gives the user the possibility to dismiss the alert view in the case that you think your error recovery was successful but the error still occurs on the next retry. To make this easier for you, the STIErrorRecoveryAttempter has a couple of convenience methods that add such an option including a localized text.

Intercepting an error

Sometimes you want to intercept an error along the way, e.g. to present it inline. To check wether you want to intercept an error you can override -[UIResponder canInterceptError:]. If you return YES, -[UIResponder interceptError:completionHandler:] will be called and the error will no longer forwarded in the responder chain. Make sure to call the completion handler.

Installation

STIErrorHandling is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "STIErrorHandling"

Please note that we version our releases based on Semantic Versioning, so it is save to advice cocoapods to use every minor and patch version within a major version.

HRSCustomErrorHandling

STIErrorHandling is a fork from the great project HRSCustomErrorHandling which is unfortunately no longer maintained.

License

STIErrorHandling is available under the Apache 2 license. See the LICENSE file for more info.