Fragments

A Fragment, in Android framework parlance, is kind of a lightweight Activity; it can be thought of as a controller for a view, rather than a view itself, but it must have a root view delegation (in Android, the role of the “view” pattern implementer from Model-View-Presenter [MVP], Model-View-Controller [MVC], Model-View-ViewModel [MVVM], etc., is filled by the View class, which is usually an atomic visual element, like a piece of text, an image, or a container of other View instances; see Chapter 2 where views are discussed in more detail).

The nice thing about Fragments, compared to Activities, is that we can instantiate them directly with custom constructor signatures, configurations, member and method access, etc. We create Fragment instances like we would any other class instance in Java. In addition, Fragments, unlike Activities, can be nested—however, there has historically been some unreliability around that, and more specifically around life-cycle callbacks, but that too is really out of scope for this chapter. Google “android fragment controversy” and you’ll find plenty of material on the topic. Again, this book chooses to remain neutral in this senseless, bloody feud.

So you create a Fragment like anything else:

Ideally, you can add your Fragment to your layout XML like you would any View:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <fragment android:name=".ListFragment"
            android:layout_width="200dp"
            android:layout_height="match_parent" />
    <fragment android:name=".DetailFragment"
            android:layout_weight="1"
            android:layout_width="0dp"
            android:layout_height="match_parent" />
</LinearLayout>

However, we are faced again with system-level, opaque instantiation. In order to configure a custom Fragment class programmatically, you’ll need to instantiate it with the new keyword and use a FragmentManager and a FragmentTransaction to add it to the existing view hierarchy.

Note you could have a custom constructor with configuration parameters here if you so choose, although when the Fragment is reconstructed, it will lose constructor arguments, so Android suggests developers use no-arg constructors and assume Fragment instances may be created with the Class.newInstance method.

From this point, since a Fragment is not a View itself, but rather a view or UI controller, it must be instructed to render using a specific View or View tree. It’s common to use a single, empty container ViewGroup like a FrameLayout to hold the View instances that represent Fragment instances.

The FragmentTransaction is able to perform a variety of update tasks for any Fragment instances you have references to. Generally, open a transaction, make all the atomic changes you want, and then commit the transaction:

Unlike Activity, the Fragment class does not extend Context and so loses direct access to many APIs; however, Fragment instances do have both a getContext and a getActivity method, so in most cases you’re just one lookup away.

Views and UI Controllers

Views and UIViewControllers are inextricably linked in iOS, such that discussing one necessitates some discussion of the other. Now, views are covered in greater depth in Chapter 2, but they’re important to note here because the root of an app’s view controller hierarchy starts on a single property of a specialized view: the app’s window, an instance of UIWindow. Every iOS application has a single UIWindow instance that the UIApplication presents. The property where the root view controller lives is the aptly named rootViewController. Setting the rootViewController of a UIWindow to a defined view controller can be done in one line:

window.rootViewController = viewController

When the root view controller is set this way, it is almost always done during an application’s launch, usually within application(_:didFinishLaunchingWithOptions:). However, going into Xcode and creating a new Single View Application project will create an application delegate that has the following code within the same method:

func application(_ application: UIApplication,
  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) ->
  Bool {
    // Override point for customization after application launch
    return true
}

Notice that nowhere in that method body is the rootViewController property set. In fact, there isn’t even a mention of a UIWindow—only a true return value. And yet, the application launches and displays a view controller created within a storyboard and seemingly never linked to or set anywhere. How very mysterious.

Xcode isn’t magic, so what’s going on here? Well, if you look closer at some other important files within this sample Xcode project, the mystery reveals itself fairly quickly.

The hunt begins

First, let’s start our detective work in a file within the project named Info.plist. This is a special file that is set within the Xcode project settings. It provides configuration values for our app via known XML keys. Within this file, there is a value for a property defined like so:

<key>UIMainStoryboardFile</key>
<string>Main</string>

The key for this property, UIMainStoryboardFile, indicates the storyboard filename the application should use when it’s starting up. The value given to this property is Main, which just happens to map to a file within this sample project named Main.storyboard. Let’s continue our hunt for clues with that file.

If we open up Main.storyboard in the visual editor within Xcode, we’ll see a single scene with a large arrow pointing toward it. Each scene in a storyboard is mapped to a UIViewController that is set within the Identity inspector on the righthand side of the screen. This is, by default, just a standard UIViewController instance, but by using the inspector it can be set to a custom subclass by typing the name of the subclass into the Class field. Our sample project has its custom class set to “ViewController,” which is a subclass defined in the project inside of ViewController.swift (Figure 1-2).

Now, about the large arrow on the left of the view controller scene: this just happens to be the “smoking gun” in our root view controller search. In the Attributes inspector within Xcode, there is a checkbox labeled “Is Initial View Controller” that is currently checked on our view controller scene. Unchecking this box makes the large arrow disappear. Build and run the app with the checkbox unchecked and you’ll get some warnings and the following error in Xcode’s console:

Failed to instantiate the default view controller
    for UIMainStoryboardFile 'Main' - perhaps the designated entry point is not
    set?

Success! We’ve found the source of our root view controller. But, how does this all string together to add our root view controller to the app’s window?

Well, on startup, the app looks for the UIMainStoryboardFile key within its Info.plist file. Inside the main storyboard file, the view controller scene that’s been set via our checkbox as our initial view controller is instantiated for the subclass given. Because it’s the initial view controller in the main storyboard, the application adds this view controller to the app window’s rootViewController property and voila! The app now has a root view controller that is displayed and active.

Figure 1-2. Storyboard editor in Xcode

You could, if you desired, achieve the same result with the following code inside the application delegate:

func application(_ application: UIApplication,
  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) ->
  Bool {
    window = UIWindow(frame: UIScreen.main.bounds)
    window?.rootViewController = UIStoryboard(name: "Main", bundle: nil).
                                   instantiateInitialViewController()
    window?.makeKeyAndVisible()
    return true
}

Let’s walk through this.

First, we set the window variable that’s defined as part of the UIApplicationDelegate protocol to a UIWindow instance that is the same size as the device’s main, and most likely only, screen via UIScreen.main.bounds. Next, the root view controller on our window object is set to a view controller. This could be any view controller we have, but in our example, we’re using the initial view controller defined in the Main.storyboard file; this is done by calling the instantiateInitialViewController() method on our UIStoryboard object.

Finally, we show this window by calling makeKeyAndVisible(). This method takes the window object and makes it the primary window of the application, displacing any other windows currently displayed.

Code versus storyboard

Now, the recommended approach for any simple app is to stick with configuration via Info.plist and the main storyboard detailed earlier. However, as an app gets more and more complex, it could become necessary, or convenient, to dive directly into the code. It’s also possible that you might prefer the codebase over storyboard configuration. There isn’t really a truly “right” way to set up your application’s starting UI controller; it’ll come down to personal preference and the requirements of the project.

Quickly, however, an application with a only single UI controller is going to become pretty limiting or incredibly complex. Let’s look at how UI controllers switch out which view is currently displayed and provide a richer experience for the app.

It’s showtime!

Let’s say we have two view controllers: one named primaryViewController and another named secondaryViewController. In this example, our currently active view controller is primaryViewController. To present secondaryViewController to the user, the simplest method would be an inherited method on UIViewController named show(_:sender:). Let’s do this in the code that follows:

// Create the view controllers
let primaryViewController = ...
let secondaryViewController = ...

// Present the secondary view controller as the active view controller
primaryViewController.show(secondaryViewController, sender: nil)

In this simple example, invoking the show(_:sender:) method would probably cause secondaryViewController to be presented modally from the bottom of the screen in front of primaryViewController. However, a key word in that previous sentence was “probably.” We don’t know with 100% certainty without more context—show(_:sender:) decouples the process of presenting the view controller from the view controller that is calling for the presentation. This is powerful and leads to simpler logic most of the time. For example, consider the following code that doesn’t use show(_:sender:):

let primaryViewController = UIViewController(nibName: nil, bundle: nil)
let secondaryViewController = UIViewController(nibName: nil, bundle: nil)

// Add the primary view controller to a navigation controller
let _ = UINavigationController(rootViewController: primaryViewController)

...

// Check if the view controller is part of a navigation controller
if let navigationController = primaryViewController.navigationController {
    // Push the view controller onto the navigation stack
    navigationController.pushViewController(secondaryViewController, animated: true)
} else {
    // Present the view controller modally because no navigation stack exists
    primaryViewController.present(secondaryViewController, animated: true, completion: nil)
}

The first thing you might notice is that we’ve introduced a new class: UINavigationController. This is a common class in iOS that helps manage a stack of view controllers; usually pushing onto or popping off a navigation controller’s stack is demonstrated in the app with a sideways transition from the right or left of the application. This is arguably the most common type of active view controller transition in iOS, possibly only behind a tab bar controller. In our preceding example, primaryViewController is added at the root of the navigation stack on the UINavigationController at instantiation.

As shown in our show-less example let’s say we wanted to add a new view controller to the stack of view controllers and make it the active view controller. First, we’d have to check if the navigationController property on primaryViewController is nil. If it’s not, the view controller is part of a navigation controller’s hierarchy, so we can then proceed to push the new view controller, secondaryViewController in this example, onto the stack by capturing the navigationController property’s value and calling the method push(_:animated:completion:) on it. If, however, the view controller doing the presenting is not on a navigation controller’s stack, we need to present this view controller in another way. In the example, we use a more direct, and older, style of presenting by calling present(_:animated:completion:).

There is more control in the code just shown, but it’s considerably more complex—and this is a simple example! What’s more, show(_:sender:) allows for some customization in how a view controller is presented as shown:

let primaryViewController = UIViewController(nibName: nil, bundle: nil)
let secondaryViewController = UIViewController(nibName: nil, bundle: nil)

// Change the presentation style and the transition style
secondaryViewController.modalPresentationStyle = .formSheet
secondaryViewController.modalTransitionStyle = .flipHorizontal

// Change the active UI controller
primaryViewController.show(secondaryViewController, sender: nil)

Here modalPresentationStyle changes the state in which the view controller is displayed, and modalTransitionStyle changes the transition that happens to get that view controller to that state. In this example, the presentation style is a Form Sheet, a specially formatted display mode for the iPad that takes up only part of the screen. The transition style is a horizontal flip that flips the view around to reveal itself.

We’ve only scratched the surface of switching out active view controllers in the app programmatically. Before we go much further, we should discuss a (somewhat) code-free option in iOS called segues.

Segues

Everything that’s been shown in code can be done in some form inside of a storyboard using segues. Segues are transitions between two view controllers; they are used to present view controllers within an app. They are most easily created within the storyboard editor in Xcode.

To create a new segue, you must first have two view controller scenes to transition between. Control-click on the source view controller scene and drag the mouse to the destination view controller within the storyboard editor. This will highlight the whole scene in blue to indicate the scene you are targeting with the mouse. Releasing the mouse will cause a pop-up to display that allows you to select the kind of segue. The options presented correspond with the options shown so far: using show(_:sender:) under the hood and letting UIKit figure out the best segue or explicitly using a modal segue, among other options.

After you create the segue, if it’s from a view controller to a view controller, you’ll need a way to programmatically call the segue. Click on the segue itself (e.g., the line connecting the scenes in the storyboard of the segue listed out as part of the scene itself like an object), open up the attributes inspector, and add a unique identifier. For our example, let’s use the name ExampleSegue.

Calling the segue is done like so:

primaryViewController.performSegue(withIdentifier: "ExampleSegue", sender: nil)

The performSegue(withIdentifier:sender:) method takes a string (ExampleSegue from earlier) and a sender, which could be any object. It’s common to pass a reference to a button if the segue was triggered via a button press, but it’s acceptable to pass in nil as we’re doing in the example.

It’s also possible to wire up a button, or other control, to trigger a segue explicitly. This is done through the same Control-click mechanism in the storyboard editor, but instead of clicking and dragging on a whole scene, click and drag on a specific button within the source view controller. This makes it easy because the segue doesn’t need to be called programmatically like before using performSegue(withIdentifier:sender:) to make the transition between view controllers occur.

Sometimes additional data needs to be provided between view controllers during a segue. There are methods called between the source and destination view controllers whenever a segue is performed allowing you to pass data or state to help set up a destination view controller or perform an action. Here is an example of a view controller presenting another view controller with the ExampleSegue, defined previously:

class ViewController: UIViewController {

    func buttonPressed(button: UIButton) {
        // Code to trigger the segue. This could also be done directly
        // on the button itself within the storyboard editor
        performSegue(withIdentifier: "ExampleSegue", sender: button)
    }

    override func shouldPerformSegue(withIdentifier identifier: String,
      sender: Any?) -> Bool {
        // This is an optional method that returns true by default
        // Returing false would cancel the segue
        return true
    }

    override func prepare(for segue: UIStoryboardSegue, sender: Any?) {
        // This is the destination view controller in the segue
        let destinationViewController = segue.destination

        // Let's pass some data to the destination segue
        ...
    }
}

Within this example UIViewController subclass, there is a method named buttonPressed(_:) that is triggered whenever a button is pressed. This code uses performSegue(withIdentifier:sender:) to trigger the segue. (This could also be accomplished by directly linking the button within the storyboard editor, but is shown to demonstrate what is happening within this class.)

Now, before the segue starts, the method shouldPerformSegue(withIdentifier:sender:) is called. This is an optional method within a view controller that can be overridden to provide some customization around the decision about whether or not a segue should be performed. The default value returned is true. The destination view controller has not been created before this method is called. Returning false will cause the segue to be cancelled, and nothing further will occur. It’s not all that common to use shouldPerformSegue(withIdentifier:sender:) to cancel segues; however, it is a useful integration point at times.

Finally, in the chain of events, prepare(for:sender:) is the last to occur. At this point, the destination view controller has now been instantiated and is one step away from being presented. This is the last chance for the source view controller to pass some state or contextual information to help the destination view controller during or after the segue.

We know how to create and set up the initial view controller in an app, and we know how to transition between active view controllers. Let’s take a step back and make sure understand the life of a view controller in iOS.

Creating UI controllers from storyboards

In order to create a view controller from a storyboard, first you must create a view controller scene in the storyboard. You can do this in Xcode by adding a view controller to the editing stage. After this has been done, make sure to open up the Identity inspector and add any custom subclass used in the Class field. Additionally, give the view controller a specific Storyboard ID. This identifier is used to identify the specific view controller scene to use when creating the view controller programmatically from a storyboard. Usually the identifier is just the name of the class, like this:

let viewController = UIStoryboard(name: "Main", bundle: nil).
                    instantiateViewController(withIdentifier: "ExampleViewController")

When view controllers are created through storyboards, UIKit uses a special method that can be overridden in the class to help with initialization. This method, init(coder:), is a great place to perform any setup or customization that needs doing before the view is loaded into the class and before it’s placed in the hierarchy of view controllers. Overriding this method is done like so:

class ViewController: UIViewController {

    required init?(coder aDecoder: NSCoder) {
        super.init(coder: aDecoder)

        // Perform some customization
    }

}

The life cycle of the UI controller is tied to the life cycle of the view it controls. There is a set of events besides the initializer the view controller receives from the view and other objects that control it to help make managing the view, and other dependent objects, easier. Let’s talk about a few of these.

viewDidLoad

This method is called after the UI controller’s view has loaded. It’s called only once during the life cycle of a view controller, and it’s the place where any view setup occurs. All outlets and actions set up inside a storyboard are wired up and ready for use at this point. Typically, things like setting a view’s background color, fonts on labels, and other stylistic operations are done within this method. Occasionally, notifications are set up here (see Chapter 11). If that is the case, make sure to unsubscribe from notification in deinit or another method to prevent crashes or memory leaks.

viewWillAppear and viewDidAppear

This set of methods is called before and after a view is presented on the tree of views that form the view hierarchy. At this point, the view often has a known size (but not always—modals do not have a view size determined until viewDidAppear) and that can be used for some last-minute size adjustments. This is also a good place to turn on memory- or CPU-intensive things like GPS tracking or accelerometer events.

viewWillDisappear and viewDidDisappear

These methods are similar to viewWillAppear and viewDidAppear, but they are triggered whenever a view is about to be, or has been, removed from the view hierarchy and is no longer visible. This is a great place to disable the things enabled in the previous set of methods.

didReceiveMemoryWarning

It’s important to handle memory warnings in iOS because memory is sometimes very constrained on mobile devices. Clear up unnecessary resource caching, clear outlets created from storyboards, etc. If the app doesn’t recover from this, it will eventually shut down and the application will be terminated.

Here’s an example of a class that handles all these methods:

class ViewController: UIViewController {
    var hugeDataFile: Any?

    required init?(coder aDecoder: NSCoder) {
        super.init(coder: aDecoder)
        // Set up operations not dependent on a view
        // For example, setting up that hugeDataFile object in the background
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        // The view has been loaded from the storyboard
        title = "Awesome View Controller Example"
    }

    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        // The view is about to be displayed on the screen
    }

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        // The view has been displayed on the screen
    }

    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        // The view is about to disappear from the screen
    }

    override func viewDidDisappear(_ animated: Bool) {
        super.viewDidDisappear(animated)
        // The view has disappeared from the screen
    }

    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
        // Uh-oh! Better clear out that huge data file we were holding on to
        hugeDataFile = nil
    }
}

Notice that all the methods are override methods that call their super equivalents in the method body. It’s important to do this, otherwise subsequent view controllers in the view controller hierarchy won’t receive calls for any missing calls. Why this isn’t a compiler addition handled just like retain and release calls is beyond the scope of this book. Just don’t forget to include these method calls in your overrides!

Navigation controllers, tab bars, and split view controllers

There are special classes in iOS that have special behavior specifically for managing view controllers. The three you’ll most likely encounter are navigation controllers (UINavigationController), tab bar controllers (UITabBarController), and split view controllers (UISplitViewController).

Navigation controllers are used to handle stacks of view controllers and make transitioning between them consistent and easier to spatially navigate and reason about versus a series of modal view controllers stacked visually on top of each other.

Tab bar controllers are a special class that handle managing active view controllers with an anchored tab bar at the bottom of the screen. This is a common method of segmenting distinct sections within an app (e.g., a tab for Search, Checkout, and Orders in a shopping app).

Split view controllers originated from the iPad but have since migrated to the iPhone. They are used to display a master set of data, typically in list form, and then provide a detail view of that data whenever an item is selected.

showDetail(_:sender:)

If you’re using a UISplitController, you can use showDetail(_:sender:) to present a detail view controller in lieu of show(_:sender:). This will adapt to a full-screen modal view when a UISplitController isn’t available for a device (as on .compact size class devices like the smaller-sized iPhones).