Mutual Mobile Engineering Blog

Mutual Mobile Engineering Blog

Introducing MMWormhole

By Conrad Stoll

MMWormhole is a shared message passing library that makes it easier to develop rich and interactive Today and WatchKit extensions. It’s designed to allow a containing app to share bits of data with its extensions, and to allow extensions to communicate state change back to the containing app.

The library solves a key challenge common to developing Today and WatchKit extensions. The containing app typically owns all of the data that an extension might need to drive its UI, but transferring that data to the extension is somewhat cumbersome. Even more challenging is notifying the app or extension in real time that a change has been made that needs to be reflected in its user interface. MMWormhole solves both of those problems to put the focus back on building a rich extension.

A good way to think of the wormhole is as a collection of shared mailboxes. An identifier, or address, is used to uniquely identify each mailbox you can send messages to. You know where a message will be delivered because of the identifier you associate with it, but not necessarily when the message will be picked up by the recipient. If the app is in the background, it may not receive the message immediately. It’s a good practice to check the contents of your mailbox when your app or extension wakes up, incase any messages were left there while you were away.

The key to data sharing between extensions and their containing app is the App Group feature introduced in iOS 8. MMWormhole sends messages as JSON objects that are saved as JSON files in the shared App Group. To continue the analogy above, the json file is basically the mailbox. Its address is the string identifier passed when sending a message.

MMWormhole also supports message listeners that sit on either side of the wormhole to observe changes to your messages. This is accomplished through the use of Darwin notification center accessed with CFNotificationCenterGetDarwinNotifyCenter. These notifications transcend time and space to tell the observers on the other side of the wormhole that a message was passed successfully through to the other side. This allows the extension or app to update its UI in real time, say for example if new data were obtained by the iOS app that the watch needs to present to the user.

We’re excited about the potential MMWormhole has to improve the experience of building extensions. We’ve worked on a few Today extensions at Mutual Mobile and are already hard at work on a few WatchKit extensions. This API reflects some of the lessons learned from that experience. We hope you’ll find it useful; as always, pull requests are greatly encouraged!

iBeacons Lessons Learned

By Sean McMains

We’ve been experimenting a lot with iBeacons lately at Mutual Mobile. We’ve done a few prototype projects, implemented them in some of our customer work, had endless conversations with iOS devs in and outside of our organization, and even had a Hackthon centered on the technology where we explored some of our more outré ideas.

There are already a lot of great articles out there on iBeacons, how they work and what they’re suited for. Rather than rehash information that other folks have already covered, I thought it might be useful to recount here a few of the lessons we’ve learned about iBeacons so far.

What You Can Do When Your App is in the Background

When your app is installed, but not in the foreground, you can find out when your device sees or stops seeing a particular iBeacon transmitter. That’s really about it.

When you move in range of a beacon for which your app has registered to receive notifications, CLLocationManager will call the didEnterRegion method on the delegate object you’ve designated in your app. When you move out of range of a beacon, it calls didExitRegion. In either case, your app gets fired up in the background for a few seconds to respond. You can call a web service, post a local notification, or just log the event for later action. You can’t reliably tell how far away from the transmitter you are, or continue to monitor changes in signal strength over time.

“But wait! If I can’t monitor signal strength, how do I make my app respond in the background only when someone gets really close to my transmitter?” The trick here is a simple one: dial down the power on your transmitter so that other devices don’t see the signal until they’re close.

AFNetworking Response Serialization With MMRecord 1.2

By Conrad Stoll

It’s been nine months since the release of MMRecord, our Objective-C library for serializing API responses into NSManagedObjects. One of the original design goals for MMRecord was to support any networking framework; we didn’t want the library to have external dependencies, in case they ever went the way of ASIHTTPRequest. But that doesn’t mean we haven’t been watching which way the wind is blowing. AFNetworking is now the standard for networking operations throughout the iOS community, and with the 2.0 release its future is even brighter. MMRecord’s core implementation will remain independent of any networking framework, but we do want to provide something special for users of AFNetworking 2.0.

We’re happy to announce AFMMRecordResponseSerializer, a response serializer for AFNetworking that returns completely parsed and populated NSManagedObject subclasses in the AFNetworking success block. The serializer uses MMRecord’s response parsing engine to parse any response object that can be represented as an array or dictionary, meaning it supports JSON, XML, or Plist HTTP response formats. And of course, all parsing happens on a background thread and managed object context.

This is all made possible by the new serialization architecture in AFNetworking 2.0. Users can now supply their own request and response serializers to provide custom functionality to use this great tool in new and interesting ways.

The main difference between the MMRecord response serializer with AFNetworking and MMRecord on its own is how you make requests. Using MMRecord directly involves making a request to a MMRecord subclass, which funnels that request through your registered server that in turn uses AFNetworking to perform the request. Using the response serializer is sort of the reverse of that. You make a request the way you would normally with AFNetworking, and then when the response comes back, the serialization system asks MMRecord to handle it.

There is some assembly required. In order for the serializer to create or fetch NSManagedObjects, it needs to be given a context and know which types of entities to look for. To do so, the response serializer should be initialized with an application’s main NSManagedObjectContext. MMRecord will takes care of performing parsing operations on a background context for you. You will also need to supply an entity mapper to the serializer. It’s the mapper’s job to associate a type of Core Data entity with a given response URL so that the correct type of entity is returned in the success block.

All of MMRecord’s parsing features are supported, including properties, relationships, deep relationships, alternate attribute names, etc. All managed object model setup occurs in the same exact way as when using MMRecord normally. Request batching works by using AFNetworking’s batching system. However, some features of MMRecord are not supported, such as pagination, MMRecord request options and custom response blocks. If any of these missing features seem important to you, please submit a pull request or open an issue and we will investigate supporting them in the future.

Check out the source code and examples in the MMRecord repo on GitHub. There’s a new example project that implements the Foursquare API using the new AFMMRecordResponseSerializer and AFNetworking 2.0. That will give you an idea of how this new extension to MMRecord works, and provides exposure to AFNetworking 2.0, as well.

Part of the beauty of great tools is that they don’t limit what people do with them, because everyone will use them differently. If you like the idea of using MMRecord to serialize requests, but don’t want to change the way you use AFNetworking, then the MMRecord response serializer for AFNetworking 2.0 may be exactly what you’re looking for.

Introduction to VIPER

By Jeff Gilbert

At Mutual Mobile we believe that testing is part of building great software. However, testing has not always been a key part of building iOS apps. As we embarked on a quest to improve testing across many of the apps that we build, we found that writing tests for iOS apps was difficult. We decided that if we were going to improve the way we test our software that we would need to first come up with a better way to architect our apps, which we call VIPER.

The traditional way of architecting an iOS app is using MVC (Model View Controller). Using MVC as an application architecture can guide you to thinking every class is either a model, a view or a controller. Since much of the application logic does not belong in a model or view it usually ends up in the controller. This leads to an issue known as Massive View Controllers, where the view controllers end up doing too much. If all of the logic is embedded in the view controller it leads to testing the logic via the UI, which is the wrong way to test logic. It is also easy to mix business logic and UI code in the same method. When you need to add functionality in the future, or fix a bug, it is often difficult to determine where to make the change and be sure it will not have unintended consequences elsewhere.


In looking for a better way to architect an iOS app I ran across the Clean Architecture, as described by Uncle Bob. Clean Architecture divides an app’s logical structure into distinct layers of responsibility. This makes it easier to isolate dependencies (e.g. your database) and to test the interactions at the boundaries between layers.

VIPER is our application of Clean Architecture to iOS apps. The word VIPER is a backronym for View, Interactor, Presenter, Entity and Routing.

Kinda Like a Spreadsheet With MMSpreadsheetView

By Jeff Lacey

The release of Apple’s Numbers on iOS brought spreadsheets to mobile users, but developers have long been left without a plug-and-play UI element to implement in their own apps.

Introducing MMSpreadsheetView

We’re happy to announce MMSpreadsheetView, an open source solution based on UICollectionView. MMSpreadsheetView presents a grid of collection view cells, with support for header rows and columns. Simply provide the data and cell classes and MMSpreadsheetView handles the layout and coordination. Although originally designed for use on iPad in full-screen, it scales down well for use in smaller views.

Under the Hood

MMSpreadsheetView coordinates up to four collection views, depending on the header configuration needed. Register your cell classes, and set the data source and delegate.

MMSpreadsheetView hooks into the collection view pan gesture recognizers to implement “exclusive touch,” which disables tap registration on other sections of the grid until the first touch ends. Also, touches are disabled when the view is in a bounce to prevent locking the view in an awkward state.

The library includes a convenience category for NSIndexPath to reduce confusion. The additions of indexPath.mmSpreadsheetRow and indexPath.mmSpreadsheetColumn represent their respective elements.

Learn More

A sample project using the view is included on our GitHub page, so head over there and check it out. The library is also available via CocoaPods.

Unit Tests That Write Themselves: Part II

By Sean McMains

In the first article in this series, we set up an abstract parent class for our view controller tests and used Objective-C’s runtime library to create dynamically named tests for all of its concrete subclasses. This technique can save a lot of time, but we still have to remember to create a new test case for each view controller class.

Is it possible to make unit tests even more automatic? By gazing deep into the occult mysteries of the runtime system, we will answer this question and, if we’re lucky, discover a little bit about love along the way. (Editor’s Note: We will not actually discover anything about love.)

If you’d like to follow along with some functional code, you can download the sample project from GitHub.

The Case for Automated Test Creation

In iOS, view controllers get certain lifecycle events from the system: viewDidLoad, viewWillAppear, viewDidAppear, viewWillDisappear and viewDidDisappear. When we write a view controller, we almost always implement some of these methods to customize its behavior.

If you’re anything like me, however, you often forget to call the superclass’ implementation of those methods, which is naughty OOP and can cause some very confusing and annoying issues. Wouldn’t it be great if we could test to make sure we remember to call super? And wouldn’t be even better if we could do so automatically?

Well, we can. (This would have have been a very short article otherwise.) Let’s take a look at how this works. (Big props to Lars Anderson, who introduced me to this technique in one of our projects. I’ve borrowed liberally from his code here.)

Unit Tests That Write Themselves: Part I

By Sean McMains

Unit tests are fantastic. They make code more robust, refactoring less scary, help developers design programs well, and allow machines do more of the monkey work involved in creating a robust app.

But let’s face it: unit tests aren’t always the most fun to write. Worse yet, if developers are trying to achieve high code coverage or adhere to Test Driven Development, they will often end up with a lot of repetitive tests.

This is a state of affairs that wouldn’t stand for a minute in application code, but which often passes without a second thought in test code. But if we’re serious about testing, this should bother us. We should strive to keep our tests as DRY1 as we keep our app.

How do we achieve this? In this article, we’ll implement a superclass for test suites with common elements, and see how to use the Objective-C runtime to make sure those tests are named meaningfully. (Teaser: in the followup article, we’ll see a technique that delves deeper into runtime kung-fu to write entire test cases automatically.)

If you’d like to follow along with some working code, you can download a sample project from GitHub. Choose the GHUnitTests target and run in the simulator to try it out.

A Note on Platforms and Testing Frameworks

The examples in this article are written with iOS, Objective-C, and GHUnit in mind, because that’s what I work with regularly. The concepts, however, should theoretically translate across to other languages and testing frameworks without much fuss.

Some of the runtime tricks here, however, rely on the testing framework doing things in a certain order. (Specifically, test cases need to be fully instantiated before the testing framework asks them what tests they have available.) GHUnit does things this way. XCTest does not, so this technique would have to be modified somewhat to work with that framework.

Introducing Lavaca 2.0

By George Henderson

Lavaca is a client-side MVC framework for developing rich internet applications across desktop and mobile devices. The Web engineering team is proud to announce a 2.0.0 release of Lavaca that includes a slew of powerful features for tackling the most challenging client-side projects.

Becoming More Modular with RequireJS

Over the past year, the most common complaint about Lavaca has been lack of true dependency management. Originally, Lavaca relied on the traditional ordering of script tags to synchronize script execution. The files were then concatenated and minified in a build process. We quickly realized that larger projects with sizable development teams needed a more scaleable solution, so we rewrote the framework in RequireJS.

RequireJS allows a developer to more clearly segment their code into modular units of functionality which can then be required as a dependency inside of other modules in the application. RequireJS will load the modules in the appropriate order based on the dependencies of the application, allowing a developer to concentrate on delivering their application instead of worrying about their scripts being in the correct order on the page.

The switch to RequireJS not only helped with code organization but also allowed us to do a few other nifty things. For instance, Lavaca no longer requires a build step or watch task during development. This results in a faster, simpler development workflow.

RequireJS provides a developer a clearer understanding of the dependencies a module has. This makes it ridiculously easy to include modules from other projects into your current project. This also allows for a developer to include components from Lavaca into non-Lavaca based projects more easily.

Build Automation with Grunt

We have replaced our build script with a development ecosystem leveraging Grunt and NodeJS. There are now tasks for starting a development server, running unit tests in a headless instance of Webkit, building to multiple environments, and packaging .ipa and .apk files. There is even a task for deploying directly to your mobile device without opening Xcode or Eclipse.

Since no two projects are the same, Grunt gives you the flexibility to modify and adjust tasks based on the individual project requirements. This flexibility means less time creating boilerplate code for new projects and much faster deployments.

Further Separation of Views

Lavaca 2.0 helps you compartmentalize and reuse pieces of your application’s UI through a new child view system. Now, any view can include nested views with their own events, templates and view-specific code for responding to user interactions.

With this architecture, you can separate the application’s UI into more discrete components. This means developers can easily work in parallel without stepping on each other’s toes, fingers, and occasionally faces. So, put your merge conflict resolution tools back on the shelf. Or at least remove them from your dock. You’ll hopefully be needing them a lot less often.


By Lars Anderson

After over a year of incubation, we are finally releasing our take on the iOS HUD paradigm - aptly named MMProgressHUD. Like drawer controllers, there are many HUD variations and implementations to choose from, so we have chosen to focus our implementation on unique, playful presentation animations and dynamic content.

While MMProgressHUD was first designed with presentation in mind, the primary, primitive functionality needed to keep the user informed of the state of an application. The need for this type of feedback is especially high during long-running, in-line tasks, like computation or network requests. MMProgressHUD keeps users informed throughout the duration of a task while providing them the mechanics to cancel tasks when deemed appropriate.


MMProgressHUD has been built from the ground up with a focus on unique and handcrafted presentation animations. We wanted a modular interface that easily enabled the addition of more presentation animations in the future. As a result, MMProgressHUD is extensible and ready to fit any app’s style. We have built several unique presentation animations (as well as conventional presentation styles) that feel very much like natural extensions to iOS.


We have handled a number of content scenarios depending on the type of information presented: large text blocks, images, indeterminate and determinate progress, as well as basic user interaction to allow users the opportunity to cancel long-running tasks. Everything is optional and customizable depending on your specific implementation.

In addition to supporting disparate content modes, MMProgressHUD automatically animates layout changes and transitions between content states.

Learn More

This is just a short overview of what MMProgressHUD has to offer. If you’re in need of a new HUD class or just want to peek under the hood, check out the source on GitHub.

iOS Side Navigation With MMDrawerController

By Kevin Harwood

Over the past year, side drawer navigation has really taken off among iOS applications, providing more flexibility than the standard built-in UITabBarController, and more content area for the selected view controller (since there is no need for a constant tab bar at the bottom). There are several projects on GitHub that attempt to solve this problem, but we were never able to find one that fit our needs here at Mutual Mobile. So we decided to venture off and write our own implementation with a few design goals in mind: extensible, lightweight, and easy to use. With that said, we’re excited to announce today that we are open sourcing what we came up with: MMDrawerController.


We’ve built a lightweight library that focuses on the user experience of side drawer navigation, and solved those problems first. We’ve also made a conscious decision not to support certain things seen in other libraries, in order to keep the library small and focused. MMDrawerController requires iOS 5.0+, uses ARC and leverages UIViewController containment to ensure the child view controller presentation methods are properly forwarded on. We’ve also made it dead simple to integrate the library into your application, so you can focus on building your application and not the corner cases and nuances of dealing with the drawer navigation paradigm.

Bells and Whistles

  • Custom gesture support for opening or closing the drawer
  • A menu button for the UINavigationBar
  • Prebuilt animations to delight the user when opening or closing the drawer
  • Support for custom drawer animations
  • A kitchen sink example to demonstrate all of the functionality

Learn More

There is much more information over on the GitHub page, so head over there and check it out. We’d love to hear your feedback or feature requests and please let us know if you find this useful!