In this article, we will define which requirements view controller containers should fulfill and, of course, how they can be implemented. This should not only provide you with hints about containers themselves, but also about view controllers in general.
To my great surprise, though view controllers are part of the everyday life of an iOS programmer, I discovered they are often misused and abused, probably due to a lack of understanding. Programmers often have a way to quickly judge the quality of some code base, mine for iOS projects is to look at how its view controllers are implemented. Implementations paying attention to details like memory exhaustion surely deserve more trust and interest than implementations barely tweaking the UIViewController Xcode template.
Before I start, please apologize for the length of this article. There is so much to be said about containers and view controllers in general that I thought the subject deserved an extensive treatment. I humbly hope this article will help demystifying this class and make you a more proficient iOS programmer.
Examples of view controller containers are available from the CoconutKit library. You may want to have a look at their implementations after you have read this article.
A definitionView controller containers are objects whose responsibility is to manage some set of view controllers, displaying or hiding them as required. Often, containers are view controllers themselves (UITabBarController, UINavigationController or UISplitViewController, for example), but this is is by no means required (UIPopoverController, for example, directly inherits from NSObject).
A remark about naming: When speaking about container objects in general, I use the term "view controller container", or simply "container". When speaking about containers which themselves inherit from UIViewController, I specifically use the term "container view controller". Please keep this distinction in mind.
Before delving into specifics, let me introduce a practical example of a container object.
Practical exampleOne common problem with view controllers is that they tend to become quite fat as a project evolves. You start with a small, clean view controller princess, and you end up with a clumsy, cluttered toad superimposing many views, powered up by thousands of lines of code barely sustainable.
In one iPad project I worked on for a bank, we had to display a detailed view for a fund. This view was made of three sections, one for a performance graph, another one for various facts about the fund (and made of several table views), and the last one for documents. We knew from the beginning that other sections would be added in the future.
Instead of stuffing everything into a single view controller, we split up our content into three view controllers: Graph data, fund facts and documents. Those view controllers were then embedded into another view controller containing some general fund information and a UISegmentedControl to toggle between sections. The result can be represented as follows, where the blue rectangle corresponds to the area where the embedded view controllers are drawn:
This is in fact a common situation I face when writing iPad applications: I often need to embed a single view controller into another one. And since I face this problem so many times, I decided to write a custom container object, HLSPlaceholderViewController, to make my life easier. Here are the requirements I decided my container implementation had to fulfill:
An HLSPlaceholderViewController container can be used to compose more sophisticated interfaces. Here is an example where one is used to create some kind of split view controller. The HLSPlaceholderViewController view contains a table view on the left and a placeholder area on the right (blue rectangle), where embedded view controllers are drawn. When clicking on an item on the left, a corresponding view controller is displayed on the right:
The requirements listed above pretty much covers every aspect I usually expect from a view controller container. While not every view controller container requires this customization level, all must exhibit common properties we discuss in the next section.
View controller container propertiesA view controller must at least fulfill two major requirements which I already mentioned in one of my previous articles about view controllers:
While the first requirement should be obvious, the second one deserves more attention since it is a tricky part in getting a container implementation right.
The view controller lifecycleIf I were to give awards to the most important documentation pages an iOS developer must read, the View Controller Programming Guide for iOS would certainly be among my favorite ones. Before iOS 5, this guide contained so much information (especially in the Custom View Controllers section) it could be quite overwhelming at first. With the new iOS 5 storyboard, the guide has been updated and is now sadly far less comprehensive that it was. Any iOS developer, though, and any container implementer in particular, should still read this guide more than once, though, because it is the only way to understand some of the subtleties associated with view controllers.
The iOS documentation and the UIViewController header file define the lifecycle of the view associated with a view controller. Let me recall it and pinpoint its numerous pitfalls:
These are the events related to view creation and display. Two additional events occur when the view disappears:
Moreover, if a memory warning is encountered during the time the view is loaded (whether it is actually visible or not), the UIViewController didReceiveMemoryWarning method is called. If the view controller's view is invisible, this method takes care of setting it to nil, calling the viewDidUnload method afterwards. To free as much resources as possible, the viewDidUnload method is therefore where you should set your view controller's outlets (and related view resources) to nil.
In essence, the view lifecycle above is a formal contract:
If a view controller container fails to implement the view lifecycle correctly (i.e. if it implements its own non-standard lifecycle), it gets poisonous and should not be used. Imagine you are implementing a view controller you want to display using such a container, and you discover that your viewWillAppear: event is not fired correctly. What can you do? If you are lucky you might be able to stuff everything in viewDidAppear: (if it gets called correctly, which I would not count on). If you are not lucky you might end up having to stuff everything in the viewDidLoad method, which is far from optimal since at that time view dimensions are not reliable (well, if the container implementation is *really* bad, they might be, making things even worse). Basically, the result you get is a view controller tightly bound to a container's implementation, not to the view lifecycle contract. Such objects are most probably incompatible with other view controller containers, and if you later need to refactor your application to use other containers, you will probably have to move code around to get it to work.
View controllers are also governed by a contract for orientation changes. We discuss it in the next section.
Handling rotationAs for the view lifecycle, rotation events are precisely defined as well. Two kinds of rotations are available:
One-step and two-step rotations cannot coexist in a same view controller implementation. If one-step rotation methods are discovered, two-step rotation methods are ignored. But this is not a severe issue since two-step rotation is deprecated (and even formally starting with iOS 5). I strongly advise you to forget about its existence altogether, and I will only discuss one-step rotation in the following.
For one-step rotation, four methods are relevant:
Besides those methods which get called for you when rotation occurs, the UIViewController interface offers an interfaceOrientation method which you can call to get the current interface orientation. The problem with this method is that it is only reliable when the view controller is displayed in a standard way (i.e. using a built-in UIKit view controller container, calling a method for modal display, or when a view controller is added as first subview of the application main window). There is a way to solve this issue, though, but we will discuss it later.
Until now, we have discussed documented properties of a view controller. Other common traits arise when using view controllers, both for convenience or efficiency reasons. We discuss them in the next section.
Informal properties of view controllersBesides lifecycle and rotation events, view controllers embedded into containers exhibit some common properties:
A remark about properties allowing to retrieve the identity of the container view controller: Besides the navigationController and tabBarController properties, UIViewController also exhibits a read-only parentViewController property. According to UIKit documentation, "parent view controllers are relevant in navigation, tab bar, and modal view controller hierarchies" (iOS 4 documentation, with slight changes in iOS 5). Since custom containers are also parent view controllers in some way, it would be tempting to have this method return custom containers as well. This can in fact be achieved using method swizzling, and it seems to work quite well at first: When the parentViewController property has been swizzled, the interfaceOrientation property suddenly returns the correct orientation (in fact the one of the container), and the navigation bar title is forwarded from the content view controller to its container view controller transparently. Seems quite nice.
But doing so, there is no way to control whether or not we want the title to be forwarded or not. We therefore sadly cannot swizzle parentViewController if we want this flexibility (and I definitely wanted it). This seems to reveal the fact that Apple's vision of view controller containers was restricted to view controller containers like UITabBarController or UINavigationController. For such containers, forwarding perfectly makes sense in all cases since they display their contents "full screen".
In general, though, a container can display several view controllers simultaneously, in which case property forwarding may not make sense. Even if a single view controller is displayed, a container might want to have its own title. This is why the UIViewController parentViewController property should IMHO never be swizzled to return custom containers, even if this would have made sense.
Designing and implementing a view controller containerNow that we have extensively discussed the many details which we must pay attention to when dealing with view controllers, let us start discussing how a view controller container can be implemented. It took me several attempts to finally get a satisfying design and properly behaving objects. I here merely concentrate on general guidelines and hints, have a look at the full implementations in CoconutKit for more juicy details.
Useful toolsBefore starting to write a container, you should consider adding a set of test view controllers to your toolbox. Here is mine for CoconutKit, and it proved to be extremely useful:
In general, I use a random color as view background color, assigned in the viewDidLoad method. This way, I am able to easily see when a view controller has been unloaded and reloaded.
Moreover, you definitely need a way to test the behavior of your container when memory warnings are received. The easiest way IMHO is to present a view controller modally in the simulator on top of the container you are writing and testing, and to fake a memory warning before dismissing it. This helps you find quickly when your container fails at releasing views, but it should not prevent you from checking the process in detail at least once by setting breakpoints or adding logging statements: I discovered a nasty bug in one of my view controllers this way
The toolbox being ready, let us discuss the implementation.
Managing view controllers in a containerAs I was iterating through container implementations, I finally started to identify behavior traits common to view controllers managed by containers. Those traits are all formal and informal requirements we discussed previously. The most important step was to isolate these traits into a single class which can be reused by several container implementations. I called this class HLSContainerContent and, as its name suggests, its only purpose is to help managing the contents of a container, i.e. its view controllers.
An instance of HLSContainerContent acts as a kind of smart pointer, taking ownership of a view controller when it is handed over to a container, and releasing ownership when the object is destroyed. Instead of having the container directly retain the view controllers it manages (which is the proper semantics to have, as we already discussed), the container retains HLSContainerContent instances, each one wrapping a single view controller it retains. The end result is therefore the same.
What is interesting with smart pointer objects is that they can set up a context which stays valid during the time ownership has been acquired. In our case, this context can store the container controller into which a view controller has been inserted. This allows us to prevent simultaneous insertion into several containers, as well as to implement methods returning the parent container of a view controller. For built-in UIKit containers, such methods have been added using categories on UIViewController, we should therefore do the same. Since we cannot add any instance variables to the UIViewController class for storing which custom container it may have been inserted to (and this is not the way I would implement it if I could), we must resort to some kind of global mapping between view controllers and container objects. This could be implemented using a global dictionary, since there are no multithreading issues to consider here (UIKit is inherently meant to be used only from the main thread). Another convenient solution to achieve the same result is to use associated objects (see runtime.h). This namely offers an easy way to virtually add instance variables to classes which we do not control the implementation of, but beware if your code must be thread-safe.
Managing content is the primary goal of the HLSContainerContent class, but not its only one, as we will see later.
Managing view controller's viewsAs said before, accessing the view property of a view controller lazily creates the view. It is therefore especially important never to access this property sloppily. To reduce the probability of making mistakes when implementing a container, I decided that view operations should only occur through HLSContainerContent. While I did not implement any mechanism to enforce it, it is easy to check that a container implementation never directly access some view controller's view property directly.
The interface of an HLSContainerContent object exhibits four methods used to manage the view associated with the view controller it wraps:
We previously discussed view caching, and why a container should not release the view associated with a view controller when it gets removed. For HLSContainerContent, this translated into separate methods for removing the view and releasing it. Moreover, the HLSContainerContent dealloc method only removes the view but does not release it. This way, even after a view controller has been removed from a container, its view can readily be used again if the view controller was retained somewhere else for caching purposes.
Transition animationsWith UIKit built-in view controller containers, you cannot choose which transition animation you want to use when displaying a view controller. This is only possible when a view controller is presented modally, but I must admit I am not really fond of the way modal transitions are implemented in UIKit: A modalTransitionStyle property on UIViewController? Seriously, why not having an additional parameter to presentModalViewController:animated:? For my custom container interfaces, I thus decided to set transition styles using a parameter given to the various methods used for presenting view controllers. This is not only clearer from a user point of view, but also far cleaner in terms of object dependencies: The modalTransitionStyle UIViewController has nothing to do in UIViewController, since UIViewController objects should not be concerned about which objects display them. Imagine all nasty cyclic references this could lead to if all containers decided to do the same...
From a usability point of view, when a view controller is added with some animation, it must be removed with the exact same inverse animation so that the user does not get confused. It therefore makes sense to use HLSContainerContent to store the transition style with which a view controller has been presented. Containers which work as a stack can later use this information when the view controller is popped.
A question naturally arises: Since the animation style is stored in HLSContainerContent, why not implement the animation code in HLSContainerContent as well so that it can be shared by all custom containers? This is what I decided to do, and the resulting code is both shorter and easier to maintain, providing all my custom containers with a variety of animations, from the usual UIKit animations (cross-dissolve, navigation controller animations) to more exotic ones. And if I later think about a new animation, all I have to do is update a single class and all my containers can readily use it. Pretty cool, uh?
When implementing a container, being able to easily generate animations and corresponding reverse animations is especially important. Imagine a container managing a stack of view controllers. When you pop a view controller, you cannot be sure that the views and frames you have to animate are the same ones you animated when the view controller was pushed. Rotations might namely have occurred in between, or maybe the views were unloaded to save some memory (e.g. as a result of a memory warning). For this reason, I recommend building a transition animation right when you need it, based on the current context (the context being which transition style to use, whether we must play the reverse animation or not, and which views are animated). This way, you guarantee that your animation looks just right. As a corollary, be especially careful if you want to cache animation parameters. Consider whether it is justified from a performance point of view (hint: Probably not), and if it really is do not forget to invalidate your cache when a rotation or a memory warning occur.
In my case, I decided to implement a single HLSContainerContent public method through which I can get a transition animation for a view controller when I need it. To get the correct animation, this method expects some context data, like the current container contents and where views are drawn. This method then simply returns an HLSAnimation object, which encapsulates various animation details: Which views are animated, how they are, whether interaction is disabled during animation, etc. The HLSAnimation class also provides a way to generate the inverse animation with a single method call, even if the animation is complex, made of several steps and involving several views.
Lifecycle eventsWhen implementing containers, the following two measures must be taken so that view lifecycle events reach contained view controllers correctly:
Let us now discuss rotation.
Rotation eventsIf your container is a view controller, implement the usual one-step animation callbacks for it. This means:
If your container is not a view controller (a case I admit I never had to implement until now), I conjecture your container should register for the UIApplicationWillChangeStatusBarOrientationNotification and UIApplicationDidChangeStatusBarOrientationNotification, and call the rotation methods for its contained view controllers from the associated callbacks. If you already had to implement such a container, I would be pleased to hear about your experience. I will try to update this article once I know more about this case.
In my view controller container implementations, I try to allow view controllers to be different depending on the interface orientation. In fact I defined a protocol, HLSOrientationCloner, which view controllers can implement to return a clone of themselves with a different orientation. In such cases, I use the willRotateToInterfaceOrientation:duration: method to instantiate the clone, and to start installing it with a cross-dissolve animation having the same duration as the rotation animation. If frame adjustments have to be done, those must not be made prior to willAnimateRotationToInterfaceOrientation:duration: being called.
One last piece of advice about rotations if your container is a view controller: I strongly recommend disabling rotation when a transition animation is playing. This could lead to undesired side-effects and is difficult to test. This should not be a nuisance to end-users who just need to try rotating their device again when the transition animation is over. An easy way to implement this behavior is to maintain an animation counter (incremented in an animation start callback, and decremented in the animation end callback), and to test it in the shouldAutorotateToInterfaceOrientation: method. If a running animation is discovered, just return NO to prevent rotation.
Pre-loading view controllers into a containerThe user should always be able to pre-load a container with view controllers before it is actually displayed. Using HLSContainerContent, this was in fact easy to achieve. Pre-loading namely does not inadvertently lead to view creation, and all properties about the view controller and the associated transition animation are encapsulated as well. All that remains to do is to implement the viewWillAppear: container method (frame dimensions are not reliable earlier) to add the pre-loaded view controller's views to the container view.
Handling a large number of view controllersSome containers might be able to load a large number of view controllers. Most of the time, such containers should fall into one of the following categories:
The code for handling large number of view controllers is inherently part of your container implementation, though again HLSContainerContent is designed to make view unloading and reloading easier. In most cases, a data source protocol can help formalizing the way view controllers are loaded.
Property forwardingLast but not the least, HLSContainerContent also provides view controllers inserted into container view controllers with the ability to "see through" the container they are in, directly reaching any navigation controller the container is itself in. To achieve this result, the following properties have to be forwarded transparently through the container when this behavior is desired:
As discussed previously, this cannot be simply achieved by having parentViewController return the container view controller. In the case of HLSContainerContainer, this was implemented by swizzling the following UIViewController getters and setters (thanks 0xced for the original idea and implementation):
When one of the above getters is called and forwarding is enabled, we check if the view controller has been associated with a container view controller. If this is the case, the getter is recursively called on the container view controller, otherwise the original implementation is called. Having the getter recursively called ensures that forwarding works even if containers are nested.
Similarly, when one of the above setters is called and forwarding is enabled, the original implementation is called, and if the view controller is associated with a container view controller, the setter is also called on it, propagating the change further away.
Since we cannot simply swizzle the parentViewController method, we also have to fix the interfaceOrientation UIViewController read-only property. This is easily achieved by swizzling it, so that when a view controller is associated with a container view controller, the container orientation is returned.
The above approach works but is not perfect from a maintenance point of view, though: If more properties are added in the future, more methods will need to be swizzled. Any suggestion is welcome.
Examples of view controller containersNow that we have discussed containers extensively, here are some examples of containers you might want to implement:
I started with HLSPlaceholderViewController and HLSStackController since these containers correspond to basic building blocks which can be nested to create more complex containers. For example, by embedding an HLSStackController into an HLSPlaceholderViewController, you could create a new kind of navigation controller. By properly designing more high-quality containers and ensuring they nest properly, you can add precious tools to your iOS programmer toolbox. Start now!
One final remark about naming conventions I apply: I tend to name containers as HLS<SomeName>ViewController if they ultimately inherit from UIViewController and if they are intended to be subclassed when used. In all other cases, I simply call containers HLS<SomeName>Controller. This rule more or less fits the naming scheme applied for UIKit built-in view controllers, with some exceptions though (UISplitViewController, for example).
iOS 5With the iOS 5 SDK, Apple engineers have introduced new API methods to help writing view controller containers. The documentation is currently rather scarce, but it seems the API can be quite useful to implement basic containers. It hasn't all the features of HLSContainerContent, but it is still a nice addition. It namely relieves the programmer from having to call most view lifecycle events (this is done for you), has support for transition animations, and introduces a clear parent-child relationship between a container and the view controllers it displays.
There is a major issue with this new API, though: Existing pre-iOS 5 container implementations need to be updated to run on iOS 5, otherwise silly bugs will appear (most notably doubled lifecycle events). This means: