Smarter ideas worth writing about.

Storyboard References

Apple's Xcode provides a robust and impressive set of tools for every stage of an iOS project's development cycle. Xcode's Git intergration has improved tremendously over the years and for most project files, a developer can easily manage their work straight from within the IDE. However, regardless if the developer is using Xcode, CLI or, another Git-client, due to Xcode's handling of the XML that generates the Storyboard's interface views, the repository management of a project’s interface files needs an extra level of attention over most other committed files. If not, a team of developers can easily step on one another and find themselves spending valuable time resolving merge-conflicts at every commit, regardless of the size of the change. 

Not only does this disruption increase costs in the end, it also influences the plan for development, which in all likelihood is not the quickest path to product. If there were multiple views in a storyboard that two developers could work on, than the developer would need to work on the views independently and in tandem, but not at the same time. A developer would always need to work off the preceding developers committed changes. Even if a developer were to simply select a user interface file in the project navigator unintentionally or to simply reference how a view is rendered, the file’s contents will automatically open in Interface Builder in the editor area of the workspace window. Regardless of if the developer added any additional functionality to any of the views, by simply opening up the interface Xcode marks the underlying XML file as changed and ready to be staged. 

Such approaches lack efficiency, increase cost and the opportunities for errors. Fortunately Apple introduced Storyboard References in iOS 9 and OS X 10.11 that can be used to alleviate many of these collaborative nightmares. To summarize, Storyboard References allow the developer to break large storyboards into smaller storyboards that then can later be referenced from any other storyboard. Instead of one extremely large storyboard, one storyboard can maintain references to smaller storyboards. For example, a "main" storyboard can contain reference storyboards of login views or a specific feature set. Additionally, with Storyboard References, storyboards are now reusable. A project can contain multiple references to one specific storyboard from any number of places.  

There are at least two approaches to incorporating Storyboard References in a project: 

  1. Refactor one or a set of views into a new storyboard from Editor->Refactor To Storyboard, found on the top menu. 
  2. Create a Storyboard Reference object and link it to a new or exiting storyboard file. 

To illustrate both examples, lets start with a relatively large storyboard file: 

Image 1

Refactor Approach

The above "Upcoming Events" views (that contain a dark blue background) could easily be refactored to a new storyboard. After selecting both of the views, one should then select "Refactor To Storyboard" From the top Editor menu (see Image 2) and finish by naming the new storyboard appropriately. Voila! Xcode places these two views into the new storyboard (Image 3) and creates a Storyboard Reference on the original storyboard (Image 4)

Image 2

Image 3

Image 4

It is important to note that the original segue to the first "Upcoming Event" view is maintained on the original storyboard. Additionally, whatever views are selected to be refactored will be placed in the new storyboard. So, if by chance only the first "Upcoming Event" view was selected and then refactored, an additional storyboard reference would be created on the new storyboard that references back to the second "Upcoming Event" view that is still on the original storyboard.

Setting new Storyboard Reference objects

The second approach is to place an empty Storyboard Reference object on a storyboard. For example, if there is a "Settings" feature that needs to be added off of the "About" view from the above project, we could start by adding the Reference first from the Object Library (Image 5).

Image 5

Via the Attributes Inspector, we can set the storyboard of the new reference to an existing or new storyboard. It is important to note that if we have just created a storyboard, its initial view controller must be set (Image 6). Via the same Attributes Inspector, we can also specify a target scene for the reference, by typing the name of the storyboard ID for that scene into the Reference ID field. If no Reference ID is specified than the scene will default to the new storyboard’s initial view controller.

Image 6

Project Management

Key to this added functionality is that a team of developers can now independently work on different storyboards. Unless a developer touches a storyboard that another developer is working on, the other developer should not anticipate any merge conflicts when pushing their work to the project repo.

However, a team’s project planning is still needed if they are to best utilize storyboard references as a way to tackle tasks. Although developers can work independently on their own storyboards, there should be a Storyboard Reference in place first on the parent branch. A suggested approach would be:

  • from a “shared” development branch, first add new storyboards based on application design wherever possible
  • create storyboard references to these new storyboards from a "main” storyboard
  • proceed with independent development on each of the storyboards with possible feature branches working on specific storyboards or off the same development branch

Merge conflicts on interface's XML files can really hamper a team’s productivity. Although Storyboard References do not alleviate the need for proper project planning, they are a welcomed tool in a collaborative development cycle.


About The Author

App Dev Consultant

Chris is part of the mobile app development team in Cardinal's Raleigh office where he is focused on native iOS solutions. After years of working in Objective-C, Chris is transitioning to Swift and continues to build familiarity with key iOS frameworks, such as CoreData, CoreAnimation and CoreBluetooth. Chris enjoys working on projects that use mobile devices to highlight or create human interactions in various spaces, such as a messaging service that communicates with Raspberry Pi’s and nearby mobile devices over Bluetooth Low Energy.