GroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupGroupSkip to Content

Version

Swift 4, iOS 11, Xcode 9

The Model-View-Controller (“MVC”) design pattern is useful, but it doesn’t scale well. As projects grow in size and complexity, this limitation becomes more apparent. In this Coordinator tutorial, you’ll try a different approach: Coordinators.

If you’re unfamiliar with the term, don’t worry! It’s a simple architecture that doesn’t require any third party frameworks, and it’s easy to adopt in your existing MVC projects.

By the end of this Coordinator tutorial, you’ll be able to decide which approach works best for you when building your apps.

By setting word, you change both kanjiList and the title that’s displayed in the UINavigationBar:

Consider for a moment. KanjiListViewController knows the following things:

There might be a word selected.

The word has kanji.

If there is no word selected, then the app should show all of the kanji in kanjiList.

KanjiListViewController knows that it’s in a UINavigationController, and that it should change the title if a word is selected.

That seems pretty complicated for something as simple as a UIViewController displaying a list of items.

One way to fix this unnecessary complexity is to pass the list of kanji to the KanjiListViewController; but who should pass it?

You can create a UINavigationController subclass and inject the data into its child, but does this code belong in the UINavigationController‘s subclass? Shouldn’t UINavigationController be a simple container for UIViewControllers?

Another problematic place is prepare(for:sender:), which is located in KanjiDetailViewController.swift:

This code means that KanjiDetailViewController knows about the next UIViewController, which in this case is KanjiListViewController.

If you were to reuse KanjiDetailViewController, the code would quickly get out of hand, because this method would need to grow into a giant switch statement so it knew which view controller to push next. This is why the logic shouldn’t be inside of another view controller — it creates a strong connection between view controllers, making them have more responsibility than they should.

Coordinator Pattern

The Coordinator pattern is a potential solution to all of the problems mentioned above. This pattern was first introduced to the iOS community by Soroush Khanlou (@khanlou) in his blog and during his presentation at the NSSpain conference.

The idea of the Coordinator pattern is to create a separate entity — a Coordinator — which is responsible for the application’s flow. The Coordinator encapsulates a part of the application. The Coordinator knows nothing of its parent Coordinator, but it can start its child Coordinators.

Coordinators create, present and dismiss UIViewControllers while keeping the UIViewControllers separate and independent. Similar to how UIViewControllers manage UIViews, Coordinators manage UIViewControllers.

Coordinator Protocol

It’s time to dive into some coding!

First, create a Coordinator protocol. From the main menu, click File\New\File…. Then, select the iOS\Source\Swift File and name the new file Coordinator.swift. When you’re done, click Next and then Create.

Now, replace its contents with the following:

protocol Coordinator {
func start()
}

Believe it or not, that’s it! All the Coordinator protocol needs is one start() function!

Apply the Coordinator Pattern

Because you want the Coordinator to handle the application’s flow, you need to provide a way, within the code, to create UIViewControllers. For this Coordinator tutorial, you’ll use .xib files instead of storyboards. With these files, you’ll be able to create UIViewControllers by calling the following:

Note: The Coordinator pattern doesn’t require that you use .xib files. You can create UIViewControllers in code, and you can also instantiate them from storyboards, which you’ll see at the end of the Coordinator tutorial.

Add these .xib files to the project target by dragging and dropping them into the Project navigator in Xcode. Open KanjiDetailViewController.xib and KanjiDetailViewController.swift in the Assistant editor and make sure that all of the outlet connections are properly set. Do the same for KanjiListViewController.xib and KanjiListViewController.swift.

Note: In the File inspector, make sure that both .xib files are added to the target.

You need to replace Main.storyboard as the application starting point.

Right-click Main.storyboard, choose Delete then click Move to Trash.

Click on the KanjiList project in the File navigator and open the KanjiList target > General, and delete Main as the Main interface:

Now you need to create your own starting point.

Application Coordinator

It’s time to create the application coordinator. Click File\New\File… and select the iOS\Source\Swift file. Name the file ApplicationCoordinator.swift. Click Next, and then Create.

Initialize applicationCoordinator with the window that you just created.

Start applicationCoordinator‘s main presentation.

Build and run the app. Now you should see the following screen:

Kanji List Coordinator

Now it’s time to present the KanjiListViewController. For this you’ll create another Coordinator. The main tasks of this Coordinator are to present a list of kanji and, later, to start another Coordinator responsible for displaying KanjiDetailViewController.

Since AllKanjiListCoordinator presents a list of all kanji, it needs a property to access the list.

Property to keep a reference to the KanjiListViewController that you’ll be presenting.

Property to store KanjiStorage, which is passed to AllKanjiListCoordinator‘s initializer.

Initialize properties.

Create the UIViewController that you want to present.

Push the newly created UIViewController to the presenter.

Now you need to create and start AllKanjiListCoordinator. To do that, open ApplicationCoordinator.swift and add this property to the top of the file, right below where you declared the rootViewController:

let allKanjiListCoordinator: AllKanjiListCoordinator

Now, in init(window:), replace all of the code below // Code below is for testing purposes // 5 with this:

Great! You just made KanjiListViewController simpler. It now has the single responsibility of displaying the list of kanji and notifying the delegate when someone selects an item. Nobody is listening yet, though.

Open AllKanjiListCoordinator.swift and add this to the end of the file, outside of AllKanjiListCoordinator:

This sets up AllKanjiListCoordinator so that it conforms to KanjiListViewControllerDelegate. Later you’ll add code inside kanjiListViewControllerDidSelectKanji(_:) that calls start() in DetailsCoordinator.

Lastly, add this code inside of start(), right below where you instantiate kanjiListViewController:

kanjiListViewController.delegate = self

Now build and run your app! Although it runs, the code inside kanjiListViewControllerDidSelectKanji is still empty, so nothing happens when you select a cell. Don’t worry; you’ll add this code shortly.

When to Create a Coordinator?

At this point, you might be wondering, “When do I need to create a separate coordinator?” There is no strict answer to this question. Coordinators are useful for a specific part of the application that might be presented from different places.

For displaying kanji details, you could create a new kanji details UIViewController inside of AllKanjiListCoordinator, and push it when the delegate callback is called. One good question to ask yourself is, “Should AllKanjiListCoordinator know about details related UIViewControllers?” The name suggests that it shouldn’t. Also, by creating a separate Coordinator for details, you’ll end up with an independent component that can display details for a kanji, without any additional dependencies on the app. This is powerful!

Suppose one day you want integrate Spotlight search. If you’ve put detail display into a separate Coordinator, it becomes simple to do: create a new DetailsCoordinator and call start().

The key takeaway is that Coordinators help create independent components that, together, build the app.

Kanji Detail Coordinator

Now let’s create the KanjiDetailCoordinator.

Similar to before, add a new file named KanjiDetailCoordinator.swift and replace the contents with the following code:

With this function, you create and start KanjiDetailCoordinator when a user selects a kanji.

Build and run.

As you can see, you now have KanjiDetailViewController presented correctly when a user selects a cell on KanjiListViewController. However, if you select a word from the list on KanjiDetailViewController, your app will crash because, like before, you’re triggering a segue that no longer exists.

Time to fix this!

Open KanjiDetailViewController.swift. Just like with KanjiListViewController, add the delegate protocol above the class declaration:

Inside of start(), add this below where you instantiated KanjiDetailViewController:

kanjiDetailViewController.delegate = self

Build and run the project. The app should work the same way as it did before the refactoring.

Project Clean Up

There are still a few things you can change to make this even better.

First of all, in KanjiListViewController.swift and KanjiDetailViewController.swift remove the prepare(for:sender:) method. You remove this code, because it will never get triggered with this architecture.

Now take a look at var shouldOpenDetailsOnCellSelection = true in KanjiListViewController.swift. This flag was used to specify whether or not the UIViewController will push KanjiDetailViewController. Since this logic is now not in the KanjiListViewController you need to make a small change.

This property allows you to set the specific accessory type for cells. The problem is now that when a word is selected, you display the kanji list with a disclosure indicator.

To fix that, open KanjiDetailCoordinator.swift and look for kanjiDetailViewControllerDidSelectWord(_:). After you instantiate wordKanjiListViewController, set its cell accessory type like this:

wordKanjiListViewController.cellAccessoryType = .none

wordKanjiListViewController‘s cellAccessoryType is set to .none, because the logic for setting this property is handled in KanjiDetailCoordinator. This saves wordKanjiListViewController from knowing too much about the application.

Now for the last improvement. Open KanjiStorage.swift and delete this static variable:

static let sharedStorage = KanjiStorage()

Deleting this static variable is not enough; it’s still in use in KanjiListViewController.swift, where you set it as the default value for kanjiList. Instead of giving kanjiList a default value of the entire KanjiStorage, display an empty list.

Change this line:

var kanjiList: [Kanji] = KanjiStorage.sharedStorage.allKanji()

To this:

var kanjiList: [Kanji] = []

Now you have a working app, with arguably cleaner and more flexible architecture, as well as no shared instances.

You can download the final project using the link at the top or bottom of this tutorial.

The Coordinator pattern might seem like an over-complication — and for a small project, it might be — but as soon as the application begins to grow, this pattern keeps the project straightforward and UIViewControllers independent. Coordinators are great, as they provide you with a clean architecture while requiring a relatively small number of changes to integrate with existing projects.

Extras: Coordinator Pattern with Storyboards

If you like storyboards, you can create a new file named Extensions.swift file and replace it with the following contents:

Returns the filename, which is the name of a class without the module name.

This is the main function; it searches for the Storyboard with the same name as defaultFileName, instantiates the first UIViewController from the Storyboard and returns it.

In the code above, you also created the StoryboardInstantiable extension for UIViewController. With it, you can just conform any UIViewController to StoryboardInstantiable, and you will be able to instantiate it.

To instantiate the UIViewController, add this code to the bottom of the UIViewController‘s file:

extension MyViewController: StoryboardInstantiable {
}

Inside the UIViewController, add the following:

let viewController = MyViewController.instantiateViewController()

For example, if you wanted to use this code with KanjiDetailViewController, it would look like the following:

With great power comes great responsibility (and limitations). To use this extension, you need to create a separate storyboard for each UIViewController. The name of the storyboard must match the name of the UIViewController‘s class. This UIViewController must be set as the initial UIViewController for this storyboard.

As a homework exercise, feel free to switch from .xib files to this approach, and please share your thoughts in the comments section below.

Where To Go From Here?

This concludes the Coordinator tutorial. One of the best advantages the Coordinator architectural pattern provides is the ability to easily change the application flow (show login screen, show tutorial screen, etc.) As an exercise in testing this, play around with the project and try creating and presenting a login screen instead of a list.

If you want to learn more about the Coordinator pattern, check out the videos below. They have some great explanations:

The coordinator pattern is one of many useful design patterns you can use in iOS development. To learn more about other patterns, check out our video series on iOS design patterns. Also check out the video tutorials on our site for in-depth explanations on other iOS topics.

As always, if you have any questions, feel free to ask in the comment section below. :]