8.
In Practice: Project "Collage Neue"
Written by Marin Todorov
Heads up... You're reading this book for free, with parts of this chapter shown beyond this point as text.
In the past few chapters, you learned a lot about using publishers, subscribers and all kinds of different operators in the “safety” of a Swift playground. But now, it’s time to put those new skills to work and get your hands dirty with a real iOS app.
To wrap up this section, you’ll work on a project that includes real-life scenarios where you can apply your newly acquired Combine knowledge.
This project will take you through:
- Using Combine publishers in tandem with system frameworks like Photos.
- Handling user events with Combine.
- Using a variety of operators to create different subscriptions to drive your app’s logic.
- Wrapping existing Cocoa APIs so you can conveniently use them in your Combine code.
The project is called Collage Neue and it’s an iOS app which allows the user to create simple collages out of their photos, like this:
This project will get you some practical experience with Combine before you move on to learning about more operators, and is a nice break from theory-heavy chapters.
You will work through a number of loosely connected tasks where you will use techniques based on the materials you have covered so far in this book.
Additionally, you will get to use a few operators that will be introduced later on to help you power some of the advanced features of the app.
Without further ado — it’s time to get coding!
Getting started with “Collage Neue”
To get started with Collage Neue, open the starter project provided with this chapter’s materials. The app’s structure is rather simple — there is a main view to create and preview collages and an additional view where users select photos to add to their in-progress collage:
Note: In this chapter, you will specifically excercise working with Combine. You’ll get to try various ways of binding data but will not focus on working with Combine and SwiftUI specifically; you will look into how to use these two frameworks together in Chapter 15, In Practice: Combine & SwiftUI.
Currently, the project doesn’t implement any logic. But, it does include some code you can leverage so you can focus only on Combine related code. Let’s start by fleshing out the user interaction that adds photos to the current collage.
Open CollageNeueModel.swift and import the Combine framework at the top of the file:
import Combine
This will allow you to use Combine types in your model file. To get started, add two new private properties to the CollageNeueModel class:
private var subscriptions = Set<AnyCancellable>()
private let images = CurrentValueSubject<[UIImage], Never>([])
subscriptions is the collection where you will store any subscriptions tied to the lifecycle of the main view or the model itself. In case the model is released, or you manually reset subscriptions, all the ongoing subscriptions will be conveniently canceled.
Note: As mentioned in Chapter 1, “Hello, Combine!,” subscribers return a
Cancellabletoken to allow controlling the lifecycle of a subscription.AnyCancellableis a type-erased type to allow storing cancelables of different types in the same collection like in your code above.
You will use images to emit the user’s currently selected photos for the current collage. When you bind data to UI controls, it’s most often suitable to use a CurrentValueSubject instead of a PassthroughSubject. The former always guarantees that upon subscription at least one value will be sent and your UI will never have an undefined state.
Generally speaking, a CurrentValueSubject is a perfect fit to represent state, such as an array of photos or a loading state, while PassthroughSubject is more fitting to represent events, for example a user tapping a button, or simply indicating something has happened.
Next, to get some images added to the collage and test your code, append the following line to add():
images.value.append(UIImage(named: "IMG_1907")!)
Whenever the user taps the + button in the top-right navigation item, which is bound to CollageNeueModel.add(), you will add IMG_1907.jpg to the current images array and send that value through the subject.
You can find IMG_1907.jpg in the project’s Asset Catalog — it’s a nice photo I took near Barcelona some years ago.
Conveniently, CurrentValueSubject allows you to mutate its value directly, instead of emitting the new value with send(_:). The two are identical so you can use whichever syntax feels better - you can try send(_:) in the next paragraph.
To also be able to clear the currently selected photos, move over to clear(), in the same file, and add there:
images.send([])
This line sends an empty array as the latest value of images.
Lastly, you need to bind the images subject to a view on screen. There are different ways to do that but, to cover more ground in this practical chapter, you are going to use a @Published property for that.
Add a new property to your model like so:
@Published var imagePreview: UIImage?
@Published is a property wrapper that wraps a “vanilla” property into a publisher - how cool is that? Since your model conforms to ObservableObject, binding imagePreview to a view on screen becomes super simple.
Scroll to bindMainView() and add this code to bind the images subject to the image preview on-screen.
// 1
images
// 2
.map { photos in
UIImage.collage(images: photos, size: Self.collageSize)
}
// 3
.assign(to: &$imagePreview)
The play-by-play for this subscription is as follows:
- You begin a subscription to the current collection of photos.
- You use
mapto convert them to a single collage by calling intoUIImage.collage(images:size:), a helper method defined in UIImage+Collage.swift. - You use the
assign(to:)subscriber to bind the resulting collage image toimagePreview, which is the center screen image view. Using theassign(to:)subscriber automatically manages the subscription lifecycle.
Last, but not least, you need to display imagePreview in your view. Open MainView.swift and find the line Image(uiImage: UIImage()). Replace it with:
Image(uiImage: model.imagePreview ?? UIImage())
You use the latest preview, or an empty UIImage if a preview doens’t exist.
Time to test that new subscription! Build and run the app and click the + button few times. You should see a collage preview, featuring one more copy of the same photo each time you click +:
You get the photos collection, convert it to a collage and assign it to an image view in a single subscription!
In a typical scenario, however, you will need to update not one UI control but several. Creating separate subscriptions for each of the bindings might be overkill. So, let’s see how we can perform a number of updates as a single batch.
There is already a method included in MainView called updateUI(photosCount:), which does various UI updates: it’ll disable the Save button when the current selection contains an odd number of photos, enable the Clear button whenever there is a collage in progress and more.
To call upateUI(photosCount:) every time the user adds a photo to the collage, you will use the handleEvents(...) operator. This is, as previously mentioned, the operator to use whenever you’d like to perform side effects like logging or others.
Usually, it’s recommended to update UI from a sink(...) or assign(to:on:) but, in order to give it a try, in this section you’ll do that in handleEvents.
Go back to CollageNeueModel.swift and add a new property:
let updateUISubject = PassthroughSubject<Int, Never>()
To exercise using subjects to communicate between different types (e.g. in this case you’re using it so your model can “talk back” to your view) you add a new subject called the updateUISubject.
Via this new subject you will emit the number of currently selected photos so the view can observe the count and update its state accordingly.
In bindMainView(), insert this operator just before the line where you use map:
.handleEvents(receiveOutput: { [weak self] photos in
self?.updateUISubject.send(photos.count)
})
Note: The
handleEventsoperator enables you to perform side effects when a publisher emits an event. You’ll learn a lot more about it in Chapter 10, “Debugging.”
This will feed the current selection to updateUI(photosCount:) just before they are converted into a single collage image inside the map operator.
Now, to observe updateUISubject in MainView, open MainView.swift and a new modifier directly below .onAppear(...):
.onReceive(model.updateUISubject, perform: updateUI)
This modifier observes the given publisher and calls updateUI(photosCount:) for the lifetime of the view. If you’re curious, scroll down to updateUI(photosCount:) and peak into the code.
Build and run the project and you will notice the two buttons below the preview are disabled, which is the correct initial state:
The buttons will keep changing state as you add more photos to the current collage. For example, when you select one or three photos the Save button will be disabled but Clear will be enabled, like so:
Presenting views
You saw how easy it is to route your UI’s data through a subject and bind it to some controls on-screen. Next, you’ll tackle another common task: Presenting a new view and getting some data back when the user is done using it.
private(set) var selectedPhotosSubject =
PassthroughSubject<UIImage, Never>()
self.selectedPhotosSubject.send(image)
model.selectedPhotosSubject.send(completion: .finished)
let newPhotos = selectedPhotosSubject
newPhotos
.map { [unowned self] newImage in
// 1
return self.images.value + [newImage]
}
// 2
.assign(to: \.value, on: images)
// 3
.store(in: &subscriptions)
isDisplayingPhotoPicker = true
selectedPhotosSubject = PassthroughSubject<UIImage, Never>()
Wrapping a callback function as a future
In a playground, you might play with subjects and publishers and be able to design everything exactly as you like it, but in real apps, you will interact with various Cocoa APIs, such as accessing the Camera Roll, reading the device’s sensors or interacting with some database.
static func save(_ image: UIImage) -> Future<String, PhotoWriter.Error> {
Future { resolve in
}
}
do {
} catch {
resolve(.failure(.generic(error)))
}
try PHPhotoLibrary.shared().performChangesAndWait {
// 1
let request = PHAssetChangeRequest.creationRequestForAsset(from: image)
// 2
guard let savedAssetID =
request.placeholderForCreatedAsset?.localIdentifier else {
// 3
return resolve(.failure(.couldNotSavePhoto))
}
// 4
resolve(.success(savedAssetID))
}
guard let image = imagePreview else { return }
// 1
PhotoWriter.save(image)
.sink(
receiveCompletion: { [unowned self] completion in
// 2
if case .failure(let error) = completion {
lastErrorMessage = error.localizedDescription
}
clear()
},
receiveValue: { [unowned self] id in
// 3
lastSavedPhotoID = id
}
)
.store(in: &subscriptions)
A note on memory management
Here is a good place for a quick side-note on memory management with Combine. As mentioned earlier, Combine code has to deal with a lot of asynchronously executed pieces of work and those are always a bit cumbersome to manage when dealing with classes.
Sharing subscriptions
Looking back to the code in CollageNeueModel.add(), you could do a few more things with the images being selected by the user in PhotosView.
let newPhotos = selectedPhotosSubject.share()
Operators in practice
Now that you learned about a few useful reactive patterns, it’s time to practice some of the operators you covered in previous chapters and see them in action.
let newPhotos = selectedPhotosSubject
.prefix(while: { [unowned self] _ in
self.images.value.count < 6
})
.share()
Challenges
Congratulations on working through this tutorial-style chapter! If you’d like to work through one more optional task before moving on to more theory in the next chapter, keep reading below.
Key points
- In your day-to-day tasks, you’ll most likely have to deal with callback or delegate-based APIs. Luckily, those are easily wrapped as futures or publishers by using a subject.
- Moving from various patterns like delegation and callbacks to a single Publisher/Subscriber pattern makes mundane tasks like presenting views and fetching back values a breeze.
- To avoid unwanted side-effects when subscribing a publisher multiple times, use a shared publisher via the
share()operator.
Where to go from here?
That’s a wrap for Section II: “Operators” Starting with the next chapter, you will start looking more into the ways Combine integrates with the existing Foundation and UIKit/AppKit APIs.