Repository files navigation

A protocol to enableUIViewControllers orUIViews to present placeholder views based on content, loading, error or empty states.

In a networked application a view controller or custom view typically has the following states that need to be communicated to the user:

• Loading: The content is currently loaded over the network.
• Content: The content is available and presented to the user.
• Empty: There is currently no content available to display.
• Error: An error occurred whilst downloading content.

As trivial as this flow may sound, there are a lot of cases that result in a rather large decision tree.

StatefulViewController is a concrete implementation of this particular decision tree. (If you want to create your own modified version, you might be interested in thestate machine that is used to show and hide views.)

Current Swift compatibility breakdown:

This guide describes the use of theStatefulViewController protocol onUIViewController. However, you can also adopt theStatefulViewController protocol on anyUIViewController subclass, such asUITableViewController orUICollectionViewController, as well as your customUIView subclasses.

First, make sure your view controller adopts to theStatefulViewController protocol.

classMyViewController:UIViewController,StatefulViewController{    // ...}

Then, configure theloadingView,emptyView anderrorView properties (provided by theStatefulViewController protocol) inviewDidLoad.

overridefunc viewDidLoad(){    super.viewDidLoad()    // Setup placeholder views    loadingView= // UIView    emptyView= // UIView    errorView= // UIView}

In addition, call thesetupInitialViewState() method inviewWillAppear: in order to setup the initial state of the controller.

overridefunc viewWillAppear(animated:Bool){    super.viewWillAppear(animated)setupInitialViewState()}

After that, simply tell the view controller whenever content is loading andStatefulViewController will take care of showing and hiding the correct loading, error and empty view for you.

overridefunc viewWillAppear(animated:Bool){    super.viewWillAppear(animated)loadDeliciousWines()}func loadDeliciousWines(){startLoading()leturl=NSURL(string:"http://example.com/api")letsession=NSURLSession.sharedSession()    session.dataTaskWithURL(url){(let data,letresponse,let error) inendLoading(error: error)}.resume()}

StatefulViewController calls thehasContent method to check if there is any content to display. If you do not override this method in your own class,StatefulViewController will always assume that there is content to display.

func hasContent()->Bool{return datasourceArray.count>0}

Optionally, you might also be interested to respond to an error even if content is already shown.StatefulViewController will not show itserrorView in this case, because there is already content that can be shown.

To e.g. show a custom alert or other unobtrusive error message, usehandleErrorWhenContentAvailable: to manually present the error to the user.

func handleErrorWhenContentAvailable(error:ErrorType){letalertController=UIAlertController(title:"Ooops", message:"Something went wrong.", preferredStyle:.Alert)    alertController.addAction(UIAlertAction(title:"OK", style:.Default, handler:nil))presentViewController(alertController, animated:true, completion:nil)}

Per default, StatefulViewController presents all configured placeholder views fullscreen (i.e. with 0 insets from top, bottom, left & right from the superview). In case a placeholder view should have custom insets the configured placeholderview may conform to theStatefulPlaceholderView protocol and override theplaceholderViewInsets method to return custom edge insets.

classMyPlaceholderView:UIView,StatefulPlaceholderView{func placeholderViewInsets()->UIEdgeInsets{returnUIEdgeInsets(top:20, left:20, bottom:20, right:20)}}

Note: The following section is only intended for those, who want to create a stateful controller that differs from the flow described above.

You can also use the underlying view state machine to create a similar implementation for your custom flow of showing/hiding views.

letstateMachine=ViewStateMachine(view: view)// Add statesstateMachine["loading"]= loadingViewstateMachine["other"]= otherView// Transition to statestateMachine.transitionToState(.View("loading"), animated:true){println("finished switching to loading view")}// Hide all viewsstateMachine.transitionToState(.None, animated:true){println("all views hidden now")}

Add the following line to yourCartfile.

github "aschuch/StatefulViewController" ~> 3.0

Then runcarthage update.

Add the following line to your Podfile.

pod "StatefulViewController", "~> 3.0"

Then runpod install with CocoaPods 0.36 or newer.

Just drag and drop the two.swift files in theStatefulViewController folder into your project.

Open the Xcode project and press⌘-U to run the tests.

Alternatively, all tests can be run from the terminal usingxctool.

xctool -scheme StatefulViewControllerTests -sdk iphonesimulatortest

• Default loading, error, empty views
• Protocol on views that notifies them of removal and add
• Views can provide delays in order to tell the state machine to show/remove them only after a specific delay (e.g. for hide and show animations)

• Create something awesome, make the code better, add some functionality,whatever (this is the hardest part).
• Fork it
• Create new branch to make your changes
• Commit all your changes to your branch
• Submit apull request

Feel free to get in touch.

• Website:http://schuch.me
• Twitter:@schuchalexander