Forem: Salah Nahed

Swift Protocol Magic II: Designing a Reusable Location Tracking System

Salah Nahed — Fri, 15 May 2026 20:24:06 +0000

How to stop rewriting CLLocationManager boilerplate in every screen — and design something your future self will actually thank you for.*

If you've shipped more than a couple of iOS apps, you've written this code. Probably more than once. Maybe more than ten times.

locationManager.delegate = self
locationManager.requestWhenInUseAuthorization()
// ...somewhere else...
func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
    // do the thing
}

And every time, you end up with the same scattered mess: a CLLocationManager instance hanging off a view controller, delegate methods sprinkled in between unrelated UI code, an if ladder for authorization status, and some half-built UI for telling the user "hey, you actually need to enable location for this to work."

It works. But it doesn't scale across an app. The second screen that needs location duplicates 80% of the first one. The third screen tweaks just enough to make extraction painful. By the fifth screen, you're copy-pasting and praying.

I hit this exact wall on WinchCore, the shared layer behind a production app I'm building. So I sat down and asked the question I should have asked years ago:

What if a view controller could become "location-aware" just by conforming to a protocol — and the framework handled the rest?

This article walks through the design I landed on. It's four small files, but they compose into something I keep reaching for in screen after screen. Let's get into it.

The wishlist

Before any code, here's what I wanted out of this:

Any view controller should be able to opt into location tracking by conforming to a protocol — no inheritance, no base class.
Authorization handling (the denied/restricted screen, the "please enable location" UI) should be centralized, not re-implemented per screen.
The restriction UI should be configurable — different screens want different titles, subtitles, and behaviors. Some screens must have location (a map). Others can tolerate the user dismissing the prompt (a profile screen showing nearby suggestions).
Testable. The whole point of touching this code was to make it possible to swap CLLocationManager for a fake in tests.
No surprises. When the screen appears, location updates start. When the user denies permission, the right UI shows up. That's it.

Four protocols. One concrete class. Let's walk through them in the order they make sense to read.

Piece 1: `LocationManager` — the abstraction

public protocol LocationManager: CLLocationManagerDelegate {
    func startTrackingLocation()
    func startUpdatingLocation()
    var currentLocation: CLLocation? { get }
}

That's it. The whole protocol.

The trick here is that it inherits from CLLocationManagerDelegate. That way any concrete implementation already has the delegate surface it needs, and from the call site you never have to think about CLLocationManager directly. You think about "tracking" and "updating" — verbs that match what your screen actually wants to do.

startTrackingLocation() is the "I just appeared, start the whole flow" entry point — authorization, delegate setup, all of it.

startUpdatingLocation() is the "I already have permission, just give me a fresh fix" version — useful when the user taps a refresh button, for example.

currentLocation is a snapshot accessor for the cases where you just want the last known coordinate without subscribing to anything.

This is the seam where testing gets easy. In a unit test, you don't construct a CLLocationManager. You construct a mock that conforms to LocationManager, return whatever location you want, and assert on what the screen does with it. No simulator GPS, no Info.plist dance, no flakiness.

Piece 2: `TrackableLocationViewController` — making any VC location-aware

public protocol TrackableLocationViewController: UIViewController {
    func handleLocationUpdate(lat: Double, lng: Double) async
    var locationManager: LocationManager { get }
}

This is the protocol your view controller conforms to. It says two things:

"I own a LocationManager."
"When a location update arrives, here's what I want to do with it."

The fact that handleLocationUpdate is async is intentional. Most of the time, when a location comes in, you're not just updating a label — you're firing off a network call to fetch nearby data, hitting a geocoder, or syncing with a backend. Making the contract async from the start means the manager can await the screen's work without us bolting on Combine pipelines or completion handler hell later.

And here's where protocol extensions earn their keep:

public extension TrackableLocationViewController {
    func startTrackingLocation() {
        locationManager.startTrackingLocation()
    }

    func startUpdatingLocation() {
        locationManager.startUpdatingLocation()
    }

    var currentLocation: CLLocation? {
        locationManager.currentLocation
    }
}

Free methods. The view controller didn't write any of this — it just gets it by conforming. Now any conforming screen can call self.startTrackingLocation() in viewDidLoad() and the system takes over.

The usage looks like this:

class MapViewController: NibViewController, TrackableLocationViewController {

    private lazy var appLocationManager: AppLocationManager = {
        AppLocationManager(locationManager: CLLocationManager(), viewController: self)
    }()

    var locationManager: LocationManager { appLocationManager }

    func handleLocationUpdate(lat: Double, lng: Double) async {
        mapView.setCenter(CLLocationCoordinate2D(latitude: lat, longitude: lng), animated: true)
        await fetchNearbyPlaces(lat: lat, lng: lng)
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        startTrackingLocation()
    }
}

Three lines of contract. The rest is your screen's actual job.

Piece 3: `LocationRestrictionConfigurable` — the "you blocked us, now what?" protocol

This is the piece I'm most proud of, because it's the one that usually gets hacked together five different ways across an app.

When the user denies location, you need to show something. A screen, an alert, a banner — whatever your designer decided. And that something is almost never identical across screens. The map screen probably wants a full-screen blocker that says "Enable location to see places near you." The profile screen might want a softer, dismissible message. Different titles, different subtitles, different blocking behavior.

So instead of hardcoding any of that into the location manager, I made it configurable through another protocol:

public protocol LocationRestrictionConfigurable: TrackableLocationViewController {
    var titleText: String? { get }
    var subtitle: String? { get }
    var shouldBlock: Bool { get }
}

Three properties. Each screen decides what it wants. And — critically — the protocol extends TrackableLocationViewController, so anywhere we need both behaviors we can compose them with the & operator and Swift's type system enforces it.

But here's the part I love: default values via protocol extension.

public extension LocationRestrictionConfigurable {
    var titleText: String? { nil }
    var subtitle: String? { nil }
    var shouldBlock: Bool { false }
}

If a screen doesn't care, it conforms and ignores. If a screen does care, it overrides just the properties it needs. No required boilerplate. No // TODO: configure this landmines.

The shouldBlock flag is the small detail that captures a real product question: can the user leave this screen without enabling location? For a map showing nearby drivers, the answer is no — the screen would be useless. For a search screen with optional location filtering, the answer is yes. The flag pushes that decision back where it belongs: with the screen itself, not with some central authorization handler making assumptions.

Piece 4: `AppLocationManager` — the concrete glue

This is where it all comes together. The full file is on the longer side, so let's read it in chunks.

The init

@MainActor
public class AppLocationManager: NSObject, LocationManager {

    private let locationManager: CLLocationManager
    private let viewController: TrackableLocationViewController & LocationRestrictionConfigurable

    public init(locationManager: CLLocationManager,
                viewController: TrackableLocationViewController & LocationRestrictionConfigurable) {
        self.locationManager = locationManager
        self.viewController = viewController
    }
}

Two things to notice.

First, @MainActor. Location callbacks touch the UI — they trigger navigation, update maps, etc. By marking the whole class @MainActor, every callback is guaranteed to run on the main thread. You don't need to wrap every callback in DispatchQueue.main.async just to be safe.

Second, the composed type in the initializer:

viewController: TrackableLocationViewController & LocationRestrictionConfigurable

This is the Swift type system doing real work for us. You literally cannot construct an AppLocationManager with a view controller that hasn't said "yes, I will track location" and "yes, I will configure my restriction UI." If you try, the compiler stops you. Bug prevented before it exists.

The deliberate delay

public func startTrackingLocation() {
    print("startTrackingLocation called from \(type(of: viewController))")
    DispatchQueue.main.asyncAfter(deadline: .now() + 1) { [weak self] in
        guard let self = self else { return }
        self.locationManager.delegate = self
        let status = self.locationManager.authorizationStatus
        self.handleLocationAuthorization(status: status)
    }
}

That one-second delay isn't laziness — it's intentional. When a screen appears, you usually want the skeleton/loading state to render first, then the permission prompt or the restriction UI to come up. If the system permission alert fires the instant viewDidLoad runs, you get a jarring experience: blank screen → modal alert → screen finally renders. Adding a small delay lets the UI breathe.

This is the kind of decision you don't see in tutorials, but you absolutely feel in production.

The authorization switch — and the nested router fallback

private func handleLocationAuthorization(status: CLAuthorizationStatus) {
    switch status {
    case .notDetermined:
        locationManager.requestWhenInUseAuthorization()
    case .restricted, .denied:
        if let router = viewController.nestedRouter {
            router.navigate(to: .locationRestricted(
                nested: true,
                title: viewController.titleText,
                subtitle: viewController.subtitle,
                shouldBlock: viewController.shouldBlock
            ))
        } else {
            viewController.router?.navigate(to: .locationRestricted(
                nested: false,
                title: viewController.titleText,
                subtitle: viewController.subtitle,
                shouldBlock: viewController.shouldBlock
            ))
        }
    case .authorizedAlways, .authorizedWhenInUse:
        locationManager.startUpdatingLocation()
    @unknown default:
        fatalError("Unknown authorization status.")
    }
}

The notDetermined and authorized cases are mechanical. The interesting case is .restricted, .denied.

When location is denied, the manager asks the view controller: do you have a nested router? If you're a child controller inside a tab bar or a container view controller, you probably want the restriction screen to present inside your container, not over the entire app. The nestedRouter is the seam for that. If there's no nested router, we fall back to the screen's main router and present it normally.

This is a small thing, but it's the kind of detail that turns a "decent abstraction" into "an abstraction I actually want to use in every screen." Real apps have nested navigation. The framework should know that.

The delegate methods

extension AppLocationManager {
    public func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
        guard let location = locations.last else { return }
        if location.coordinate.latitude == 0 || location.coordinate.longitude == 0 { return }

        Task {
            await viewController.handleLocationUpdate(lat: location.coordinate.latitude,
                                                      lng: location.coordinate.longitude)
        }
        manager.stopUpdatingLocation()
    }

    public func locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus) {
        handleLocationAuthorization(status: status)
    }

    public func locationManager(_ manager: CLLocationManager, didFailWithError error: Error) {
        print("AppLocationManager locationManager error: \(error)")
    }
}

Three things to point out:

The (0, 0) guard. On rare occasions, CLLocationManager will hand you a coordinate of (0, 0) — which is technically a real place in the Atlantic Ocean off the coast of Africa, but practically always means the GPS hasn't acquired a real fix yet. Filtering those out is a small piece of defensive code that saves you from rendering a map of the open sea.
Task { await ... } bridges the worlds. The delegate callback is synchronous, but handleLocationUpdate is async. Wrapping it in a Task lets the screen's async work run without blocking the delegate.
stopUpdatingLocation() after the first fix. This particular flow is one-shot — we want a single accurate location, not a continuous stream. If you needed continuous tracking (turn-by-turn navigation, fitness tracking), you'd skip this line. But for "where is the user right now so I can fetch nearby data," one fix is usually enough, and it's much better for battery.

Why this design pays off

Let me zoom out, because the pieces individually are small, but the system they form is the point.

Adding location tracking to a new screen takes about five lines. Conform to the two protocols, provide a LocationManager, implement handleLocationUpdate, call startTrackingLocation() in viewDidLoad. Done. Every other concern — authorization, restriction UI, blocking behavior, threading — is handled.

Testing is trivial. Mock LocationManager, feed it whatever location you want, assert on what handleLocationUpdate does. No real GPS, no real CLLocationManager, no flakiness.

Customization is opt-in. Want a different restriction title for this screen? Override titleText. Want this screen to block until location is enabled? Set shouldBlock to true. Don't care? Conform and move on with your day.

The compiler enforces the contract. You can't construct an AppLocationManager with a view controller that's missing either protocol. The bug where someone forgets to handle restriction UI literally cannot exist.

The main thread is guaranteed. @MainActor removes a whole category of "why is my UI updating weirdly" bugs that come from delegate callbacks not being on the main thread.

What I'd add next

Honest reflection — this design isn't done. Things I'd evolve in a future version:

Continuous tracking mode. Right now it's one-shot. A TrackingMode enum (oneShot, continuous, significantChanges) would make it more flexible.
Last-known-location caching. For screens that just want a rough location to fetch initial data, returning the last cached fix immediately would feel snappier.
Background location — a whole separate beast that deserves its own protocol layer.
Replace print with a proper logger — the current print statements were debugging aids that lingered. A real app should route these through os.Logger or whatever your logging story is.

But none of these change the core shape. They extend it.

Takeaways

If you take one thing from this, let it be this: the magic isn't the code, it's the seams.

The seams are where you draw the lines between what a view controller knows and what the framework handles. Protocols are the tool for drawing those lines cleanly. Default implementations are how you keep them ergonomic. Composed types (A & B) are how you let the compiler enforce them.

When you find yourself copy-pasting the same setup code into yet another view controller, that's the signal. There's a protocol hiding in there. Pull it out, give it defaults, compose it with what's already there.

That's all "Protocol Magic" really is — recognizing those moments and acting on them.

If you missed part one — Swift Protocol Magic: Building a Beautiful, Reusable Option Selection System — it applies the same thinking to bottom sheets and option pickers. And if you're curious about navigation patterns, AppRouter-UIKit is an iOS navigation library I open-sourced that uses similar protocol-oriented ideas.

👋 A quick note: I'm currently open to new opportunities. After 10+ years building iOS apps (and Flutter more recently), I'm looking to join an amazing team — ideally an international, on-site role — where I can keep building things like this. If your team is hiring, or you just want to talk iOS architecture, please reach out on any channel below.

📩 Connect with me on LinkedIn
Follow my tech journey
🐦 Twitter/X: @salahamassi
📸 Instagram: @salahamassi
🐙 GitHub: salahamassi

Let's build something elegant together. ❤️

Design-Driven Firebase in Flutter: Building Custom In-App Messaging with SwiftUI & Compose

Salah Nahed — Sun, 08 Feb 2026 20:53:54 +0000

🆕 Design-Driven Firebase in Flutter: Building Custom In-App Messaging with SwiftUI & Compose

In-app messaging plays a critical role in how users interact with modern apps — from promoting offers to driving engagement and retention.
Published on: April 11, 2025 · ⏱️ 10 min read

Android Ain’t Easy: Crafting Custom FIAM with Compose

Setting Up Jetpack Compose: The First Brick in the Wall 🧱

Before diving into the custom renderer, we first needed to enable Jetpack Compose in our Flutter project’s native Android layer. This meant updating the build.gradle file with the proper buildFeatures, setting the kotlinCompilerExtensionVersion, and pulling in all the right dependencies.

buildFeatures {
    compose true
}

composeOptions {
    kotlinCompilerExtensionVersion = "1.4.8"
}

Then we added the essential Compose libraries:

// Compose BOM
implementation platform("androidx.compose:compose-bom:2025.02.00")

// Core UI
implementation "androidx.compose.ui:ui"
implementation "androidx.compose.ui:ui-tooling-preview"
implementation "androidx.compose.material3:material3"

// Runtime
implementation "androidx.activity:activity-compose:1.10.1"

// For debugging previews
debugImplementation "androidx.compose.ui:ui-tooling"

🧨 Why version `1.4.8`?

Because if you go any higher while using Kotlin 1.8.22 (which Flutter ships with), Compose will politely scream at you. We initially tried newer versions, only to be met with this charming message:

This version of the Compose Compiler requires Kotlin version 1.9.23 but you are using 1.8.22 which is not known to be compatible…

📌 Check the Compose-Kotlin compatibility table for more details.

Then it hits you with the legendary line:

"…or suppressKotlinVersionCompatibilityCheck but don’t say I didn’t warn you!"

Yeah. Compose isn’t messing around 😅.

So we locked it down to 1.4.8, which plays nicely with the Kotlin version Flutter currently ships.

Replacing the Default: Building Our Custom In-App Renderer

Firebase tells us: implement FirebaseInAppMessagingDisplay and register it. That’s all. No examples, no docs for Compose. Just vibes.

FirebaseInAppMessaging.getInstance().setMessageDisplayComponent(NologyInAppMessageDisplay(context))

Let's walk through the custom implementation we built — clean, robust, and fully integrated with your Compose UI.

🧠 The Heart of the Custom FIAM: `NologyInAppMessageDisplay`

class NologyInAppMessageDisplay(private val context: Context) : FirebaseInAppMessagingDisplay {
    override fun displayMessage(
        inAppMessage: InAppMessage,
        callbacks: FirebaseInAppMessagingDisplayCallbacks
    ) {
        // Implementation logic
    }
}

✅ What This Class Does:

Confirms message type: Only supports ModalMessage.
Loads remote image manually (unlike iOS).
Extracts button styles and parses appData for optional buttons.
Wraps the Composable inside a DialogFragment.
Handles actions and calls messageClicked() / messageDismissed().

🔍 Platform Differences: iOS vs Android

📸 Image Handling

iOS: Uses imageRawData directly, no network call required.
Android: Must manually download image from imageUrl.

🔗 Deep Linking

iOS: Firebase automatically opens links.
Android: Must manually launch an Intent.ACTION_VIEW with the URL.

🧪 How to Test Custom In-App Messages

Firebase caches campaigns for up to 24 hours — but test mode lets you bypass that using a device’s FID (Firebase Installation ID).

Step 1: Get the FID

On Android:
Look for this in Logcat:

I/FIAM.Headless: Starting InAppMessaging runtime with Installation ID <YOUR_ID>

On iOS:
Go to Xcode → Product > Scheme > Edit Scheme…
Add argument: -FIRDebugEnabled
Then find in logs:

[Firebase/InAppMessaging] Starting InAppMessaging runtime with Firebase Installation ID <YOUR_ID>

Step 2: Send a Test Message

Go to Firebase → In-App Messaging → New Campaign
Select Modal layout (⚠️ Only one supported by custom renderer)
Add custom data:

{
  "secondaryTitle": "SKIP",
  "secondaryTextColor": "#000000",
  "secondaryBackgroundColor": "#C9C9C9"
}

Click Test on your device
Paste the FID
Reopen app — message should appear instantly 💥

🔗 About Deep Links?

Setting up proper deep link support is a big deal — and deserves its own article.

I’ll cover everything in a future piece:

App links & Universal Links
Domain verification
JSON files for each platform
Mapping paths into Flutter navigation

If that sounds helpful — drop a comment and I’ll prioritize it!

✅ Wrapping Up

Building custom layouts for Firebase In-App Messaging isn’t just about styling — it’s about creating immersive, native, analytics-driven experiences that match your app’s personality and performance goals.

From deep link support to analytics tracking, we stayed close to Firebase’s native protocols while still delivering a UI that feels ours.

🙋‍♂️ Who’s Behind This?

I’m Salah Nahed, a Flutter & mobile craftsman passionate about building beautiful cross-platform experiences.

📦 Creator of Bond
💼 Available for consulting & freelancing
🧠 Follow me for more dev stories

Let’s connect:

🔗 LinkedIn
🐦 Twitter/X
🐙 GitHub
📸 Instagram

Thanks for reading — and see you in the next deep dive ✌️

Swift Protocol Magic: Building a Beautiful, Reusable Option Selection System

Salah Nahed — Sat, 05 Apr 2025 13:57:40 +0000

🎨 Paragraph 1: The Artist’s Pain

“This is not just code. This is me painting on a blank canvas.”

I come from Gaza — a place where electricity is a luxury and quiet nights are often interrupted by warplanes, not whispers. And yet, in the middle of this chaos, I found peace in writing code. Not just any code — but code that feels like art. Clean. Modular. Elegant.

I still remember the first time I fell in love with programming. It wasn’t just the logic, the problem-solving, or the satisfaction of building something from nothing. It was the way code flowed under my fingers, like a brush on canvas. A silent, invisible dance between what I imagine and what becomes real. I wasn’t writing software. I was composing symphonies, designing cities, crafting worlds.

When I built the Winch options system, I didn’t just want it to work—I wanted it to feel alive, composable, magical. I wanted every line of code to be an expression of intent, every protocol to feel like a piece of poetry. This story is the journey of building that. Of how I turned chaos into clarity. Of how I wrote my favorite piece of code yet.

🌱 Paragraph 2: The Root of Repetition

In a logistics app like Winch, we have tons of dropdowns, multi-selects, and filters: cities, regions, vehicle types, services, roles, branches… and the list goes on.

Initially, each screen hardcoded its options UI. The same boilerplate repeated again and again:

Fetch data from an endpoint.
Transform it into a UI-friendly model.
Present it in a table.
Handle selection and formatting.

It was error-prone. It was boring. And most of all—it was ugly.

So I paused. I stared at the patterns. And I asked myself: what would a painter do?

🚀 Paragraph 3: A Vision of Harmony

I paused. I thought: What if I never had to write the logic to load cities again? What if the structure of filterable data—be it from API or static JSON—could be abstracted into a single, elegant protocol?

I wanted something composable. Beautiful. Something that could give a junior developer superpowers, and make a senior developer smile. It had to be flexible enough to support API queries, yet simple enough to handle a static array.

I wanted a world where I could write:

createOptionsViewController(
    type: Cities.self,
    view: citySelectionView,
    keyPath: \.selectedCities
)

...and everything would just work.

No repetitive fetching logic.
No custom transformers.
No boilerplate UI config.

Just types.
Just intent.
Just beauty.

So I opened Xcode, created a new file, and named it: MenuType.swift.

🛠️ Paragraph 4: The Craft — One Protocol to Rule Them All

This was the beating heart of the system:

The Protocol:

public protocol MenuType {
    init()
    typealias MenuLoaderCompletion = (Result<[OptionModel], WinchError>) -> Void
    var path: String { get }
    var staticData: [OptionModel]? { get }
    func allCases(query: [String: String], completion: @escaping MenuLoaderCompletion)
    associatedtype Model: SwiftyModelData
    func provideCustomType() -> Model.Type
    func provideCustomTypeMaper(_ data: [Model]) -> [OptionModel]
}

Each property and function had a purpose:

path: The API endpoint.
staticData: Optional fallback data.
allCases(query:): Unified entry point for loading data.
provideCustomType: Defines the decoding target.
provideCustomTypeMaper: Lets you transform your decoded model into UI-friendly OptionModels.

The Default Implementation:

public extension MenuType {
    var staticData: [OptionModel]? { nil }

    func provideCustomType() -> OptionModel.Type {
        OptionModel.self
    }

    func provideCustomTypeMaper(_ data: [OptionModel]) -> [OptionModel] {
        data
    }

    func allCases(query: [String: String], completion: @escaping MenuLoaderCompletion) {
        loadData(query: query, completion: completion)
    }

    private func loadData(query: [String: String], completion: @escaping MenuLoaderCompletion) {
        if let staticData = staticData {
            completion(.success(staticData))
            return
        }

        var fullPath = path
        if !query.isEmpty {
            let queryString = query.map { "\($0.key)=\($0.value)" }.joined(separator: "&")
            fullPath += "?\(queryString)"
        }

        let networkService = NetworkApiDataSourceService(
            path: fullPath,
            domain: WinchConfiguration.shared.apiURL,
            method: "GET",
            params: [:],
            arrayRequest: true
        )

        let appDataSource = WinchConfiguration.shared.appDataSource
        appDataSource.perform(service: networkService, provideCustomType()) { result in
            switch result {
            case .array(let data):
                let options = provideCustomTypeMaper(data.data)
                completion(.success(options))
            case .failure(let error):
                completion(.failure(error.convertToWinchError()))
            default: break
            }
        }
    }
}

This default logic was a revelation. Suddenly, 80% of my filters only needed to implement a path.

But the real power came when I needed something custom.

🧱 OptionModel & SelectableModel

These two simple models hold the entire selection experience together:

public struct OptionModel: Equatable, PresentableModel, Comparable {
    public let id: String
    public let name: String
    public let icon: String?
    public let children: [OptionModel]?
    public let additionalData: [String: Any]?

    public init(id: String, name: String, icon: String? = nil, children: [OptionModel]? = nil, additionalData: [String: Any]? = nil) {
        self.id = id
        self.name = name
        self.icon = icon
        self.children = children
        self.additionalData = additionalData
    }

    public var idValue: String { id }
    public var presentableValue: String { name }

    public static func < (lhs: OptionModel, rhs: OptionModel) -> Bool {
        if let left = Int(lhs.id), let right = Int(rhs.id) {
            return left < right
        }
        return lhs.id < rhs.id
    }
}

struct SelectableModel<T> {
    let model: T
    var selected: Bool
    var children: [SelectableModel<T>]?
}

OptionModel represents a selectable item. It can hold an icon, nested children, and extra metadata (additionalData).
SelectableModel wraps any T, tracks its selection state, and optionally supports children (for grouped filters).

This duo powers the entire OptionsViewController rendering and sync logic.

🧠 Real-World Customization: `Cities.swift`

Some use cases need more than the default—more structure, more transformation. Let me show you a real example: the Cities filter, where I needed to display cities grouped by their region.

public struct Cities: MenuType {
    public init() {}

    public var path: String {
        "cities"
    }

    public func provideCustomType() -> Cities.City.Type {
        City.self
    }

    public func provideCustomTypeMaper(_ data: [City]) -> [OptionModel] {
        let validCities = data.filter {
            $0.region.id != 0 && !$0.region.name.isEmpty
        }

        let grouped = Dictionary(grouping: validCities, by: { $0.region })

        return grouped.map { region, cities in
            OptionModel(
                id: "\(region.id)",
                name: region.name,
                children: cities.map {
                    OptionModel(
                        id: "\($0.id)",
                        name: $0.name,
                        additionalData: $0.toJSON().dictionaryObject
                    )
                },
                additionalData: [
                    "region_id": region.id,
                    "region_name": region.name
                ]
            )
        }.sorted()
    }

    public struct City {
        let id: Int
        let name: String
        let region: Region

        struct Region: Hashable {
            let id: Int
            let name: String
        }
    }
}

extension Cities.City: SwiftyModelData {
    public init(json: JSON) {
        id = json["id"].intValue
        name = json["name"].stringValue
        region = Region(
            id: json["region"]["id"].intValue,
            name: json["region"]["name"].stringValue
        )
    }

    public func toJSON() -> JSON {
        JSON([
            "id": id,
            "name": name,
            "region": [
                "id": region.id,
                "name": region.name
            ]
        ])
    }
}

This is where the protocol shines. The network logic? Already handled. The query injection? Already handled. The decoding? Check. All I had to do was focus on how I want to shape the data—and thanks to provideCustomType and provideCustomTypeMaper, I did exactly that.

Clean. Elegant. Reusable.

🎬 Paragraph 6 – BaseOptionsConfigurable: One Interface, Two Destinies

Designing reusable UI logic isn’t just about making things work — it’s about making them feel inevitable, like the pieces were always meant to fit this way. That’s exactly what BaseOptionsConfigurable does. It acts like the unsung hero at the center of our architecture — abstract enough to be reused, yet powerful enough to orchestrate everything from visual rendering to syncing logic between views and controllers.

Let’s break it down.

@MainActor
protocol BaseOptionsConfigurable: UIResponder {
    var optionsBottomSheet: OptionsBottomSheetView { get set }

    func render<T: MenuType>(
        _ values: [OptionModel]?,
        to view: WinchItemView,
        and controller: OptionsViewController<T>,
        formatter: (([OptionModel]) -> String)?
    )
}

This protocol isn’t meant to be used directly — it’s a bridge. The foundation for its two children:

OptionsConfigurable: stores values locally until submission.
APIOptionsConfigurable: sends values immediately to the backend.

They both need to show a bottom sheet, both need to render values in UI, and both need to sync selections between a WinchItemView and the internal controller. So instead of repeating all that boilerplate, we put it here. Once. Forever.

🧪 The Render Flow (Extension Breakdown)

extension BaseOptionsConfigurable {
    func render<T: MenuType>(
        _ values: [OptionModel]?,
        to view: WinchItemView,
        and controller: OptionsViewController<T>,
        formatter: (([OptionModel]) -> String)? = nil
    ) {
        let newValues = values ?? []
        controller.syncSelectedValues(newValues)
        renderItemValue(newValues, to: view, formatter: formatter)
    }

    func renderItemValue(
        _ values: [OptionModel],
        to view: WinchItemView,
        formatter: (([OptionModel]) -> String)? = nil
    ) {
        guard !values.isEmpty else {
            view.value = nil
            return
        }

        let formattedValue = formatter?(values) ?? {
            let count = values.count
            let moreKeyword = "keyword.more".localized
            return count == 1
                ? values.first!.name
                : "\(values.first!.name) +\(count - 1) \(moreKeyword)"
        }()

        view.borderColor = .deActivatedBorderColor
        view.value = formattedValue
    }
}

🧠 Let’s Understand the Parameters

values: the selected options, usually returned from the controller or from initial defaults.
view: the UI component (WinchItemView) that shows the current selection.
controller: an OptionsViewController, which manages selectable data and updates.
formatter: an optional closure that lets you override the text shown in the UI.

If no formatter is provided, we gracefully fall back to:

Show the first option name if there's only one.
Or show "City A +2 more" if you selected three.

This small detail is what makes the UI feel human.

In sum, BaseOptionsConfigurable gave us a canvas. A way to inject logic into any screen — whether it’s API-backed or form-bound — and let the screen render, sync, and behave like it belongs in a bigger system.

Because it does.

🧰 `OptionsViewConfig`: The Behavior Controller

The OptionsViewConfig struct allows you to tweak the behavior of the options view — from enabling search to customizing the save button, and even how selected values appear in the UI.

The Code:

public struct OptionsViewConfig {
    public var enableSearch: Bool
    public var actionButtonTitle: String?
    public var formatter: (([OptionModel]) -> String)?

    public init(
        enableSearch: Bool = true,
        actionButtonTitle: String? = nil,
        formatter: (([OptionModel]) -> String)? = nil
    ) {
        self.enableSearch = enableSearch
        self.actionButtonTitle = actionButtonTitle
        self.formatter = formatter
    }

    public static var `default`: OptionsViewConfig {
        OptionsViewConfig()
    }
}

What Each Property Does:

enableSearch: Turns on the search bar in the bottom sheet.
actionButtonTitle: Allows you to change the text of the save button.
formatter: Lets you customize how selected values are rendered in the UI (e.g. "Selected: 3 Items").

Example:

OptionsViewConfig(
    enableSearch: true,
    actionButtonTitle: "CONTINUE",
    formatter: { options in "Selected: \(options.count)" }
)

This makes your bottom sheet more expressive, localized, and fine-tuned for each use case.

⚙️ Paragraph 7: Configurable Power — Local vs. Live

So far, we had the MenuType to load options — but what happens after that?

When a user taps on a WinchItemView, we need to show the available options and handle what happens after selection. Should we save the data locally? Should we call the API immediately? That's where the OptionsConfigurable and APIOptionsConfigurable protocols come in.

They are two distinct philosophies for managing user selections:

Feature	`OptionsConfigurable` (FormData)	`APIOptionsConfigurable` (API)
Where values are stored?	In local `formData`	Immediately sent to API
When API is called?	On final form submission	Instantly after user clicks Action button
Error handling?	None needed	Shows alert and prevents sheet from closing
Bottom Sheet Behavior	Always closes after selection	Closes only if API call succeeds

🧩 `OptionsConfigurable`

Designed for scenarios like forms or delayed submissions. You store user selections locally, then send them later.

Protocol Definition:

@MainActor
public protocol OptionsConfigurable: BaseOptionsConfigurable {
    associatedtype FormData
    var formData: FormData { get set }
    func createOptionsViewController<T: MenuType>(
        type: T.Type,
        view: WinchItemView,
        defaultValues: [OptionModel]?,
        keyPath: WritableKeyPath<FormData, [OptionModel]?>,
        didSelectValues: ValueCallBack<[OptionModel]?>?,
        optionsConfig: OptionsViewConfig
    ) -> OptionsViewController<T>
}

Default Implementation:

public extension OptionsConfigurable {
    func createOptionsViewController<T: MenuType>(
        type: T.Type,
        view: WinchItemView,
        defaultValues: [OptionModel]? = nil,
        keyPath: WritableKeyPath<FormData, [OptionModel]?>,
        didSelectValues: ValueCallBack<[OptionModel]?>? = nil,
        optionsConfig: OptionsViewConfig = .default
    ) -> OptionsViewController<T> {
        let viewController = OptionsViewController<T>(
            didSubmitSelectedFilters: { [weak self] selectedOptions in
                guard let self = self else { return }
                didSelectValues?(selectedOptions)
                self.renderItemValue(selectedOptions, to: view, formatter: optionsConfig.formatter)
                self.formData[keyPath: keyPath] = selectedOptions
                self.optionsBottomSheet.hide()
            },
            defaultFilters: defaultValues,
            hideNavigationBar: true,
            singleSelectionMode: false,
            enableSearch: optionsConfig.enableSearch,
            actionButtonTitle: optionsConfig.actionButtonTitle
        )

        viewController.title = view.title

        if let defaultValues = defaultValues {
            formData[keyPath: keyPath] = defaultValues
            render(defaultValues, to: view, and: viewController, formatter: optionsConfig.formatter)
        }

        view.actionButtonTapped = { [weak self] in
            self?.optionsBottomSheet.setOptionViewController(viewController, title: view.title ?? "")
            self?.optionsBottomSheet.show()
        }

        return viewController
    }
}

Parameter Breakdown:

Parameter	Type	Purpose
`type`	`T.Type`	The type that conforms to `MenuType`. This tells the controller which menu to load.
`view`	`WinchItemView`	The visual component that triggered the options sheet. We render selected values back into this view.
`defaultValues`	`[OptionModel]?`	Preselected values to be shown when the bottom sheet opens.
`keyPath`	`WritableKeyPath<FormData, [OptionModel]?>`	Specifies where in your form data the selected values should be stored.
`didSelectValues`	`(Optional) ValueCallBack<[OptionModel]?>`	Callback triggered when the user confirms their selection. Useful for reacting immediately in your view controller.
`optionsConfig`	`OptionsViewConfig`	Configures behavior such as search bar visibility, save button title, and how the selected values should be formatted.

⚡️ `APIOptionsConfigurable`

Designed for real-time updates. As soon as the user picks something and taps the action button, we hit the API and only close the sheet if the request is successful.

Protocol Definition:

@MainActor
public protocol APIOptionsConfigurable: BaseOptionsConfigurable {
    var appDataSource: WinchDataSource { get set }
    func createOptionsViewController<T: MenuType, R: SwiftyModelData>(
        type: T.Type,
        view: WinchItemView,
        defaultValues: [OptionModel]?,
        apiPath: String,
        apiKey: String,
        cachePath: String?,
        responseType: R.Type,
        didSelectValues: ValueCallBack<[OptionModel]?>?,
        optionsConfig: OptionsViewConfig
    ) -> OptionsViewController<T>
}

Default Implementation:

public extension APIOptionsConfigurable {
    func createOptionsViewController<T: MenuType, R: SwiftyModelData>(
        type: T.Type,
        view: WinchItemView,
        defaultValues: [OptionModel]? = nil,
        apiPath: String,
        apiKey: String,
        cachePath: String? = nil,
        responseType: R.Type,
        didSelectValues: ValueCallBack<[OptionModel]?>? = nil,
        optionsConfig: OptionsViewConfig = .default
    ) -> OptionsViewController<T> {
        let viewController = OptionsViewController<T>(
            didSubmitSelectedFilters: { [weak self] selectedOptions in
                guard let self = self else { return }
                didSelectValues?(selectedOptions)

                Task {
                    let data = await self.submitSelectedFilter(
                        selectedOptions: selectedOptions,
                        apiPath: apiPath,
                        apiKey: apiKey,
                        cachePath: cachePath,
                        responseType: responseType
                    )
                    if let _ = data {
                        self.renderItemValue(selectedOptions, to: view, formatter: optionsConfig.formatter)
                        self.optionsBottomSheet.hide()
                    }
                }
            },
            defaultFilters: defaultValues,
            hideNavigationBar: true,
            singleSelectionMode: false,
            enableSearch: optionsConfig.enableSearch,
            actionButtonTitle: optionsConfig.actionButtonTitle
        )

        viewController.title = view.title

        if let defaultValues = defaultValues {
            render(defaultValues, to: view, and: viewController, formatter: optionsConfig.formatter)
        }

        view.actionButtonTapped = { [weak self] in
            self?.optionsBottomSheet.setOptionViewController(viewController, title: view.title ?? "")
            self?.optionsBottomSheet.show()
        }

        return viewController
    }
}

Parameter Breakdown:

Parameter	Type	Purpose
`type`	`T.Type`	The menu type to be loaded. Must conform to `MenuType`.
`view`	`WinchItemView`	The view where selected values are displayed.
`defaultValues`	`[OptionModel]?`	Initial selections to show in the options list.
`apiPath`	`String`	The API endpoint that receives the selection on submit.
`apiKey`	`String`	The key used to send the selected IDs in the request payload.
`cachePath`	`(Optional) String`	Path used for caching responses (if any). Improves offline performance.
`responseType`	`R.Type`	The model type expected from the API response. Must conform to `SwiftyModelData`.
`didSelectValues`	`(Optional) ValueCallBack<[OptionModel]?>`	Called when the user selects options, before the API call.
`optionsConfig`	`OptionsViewConfig`	Customize UI (search, formatting, save button title).

👇 Example: `AddBusinessUserViewController`

class AddBusinessUserViewController: NibViewController, OptionsConfigurable {

    struct FormData {
        var branches: [OptionModel]?
        var role: OptionModel?
    }

    var formData = FormData()
    var optionsBottomSheet = OptionsBottomSheetView()

    @IBOutlet weak var branchesWinchItemView: WinchItemView!
    @IBOutlet weak var roleWinchItemView: WinchItemView!

    private lazy var branchesViewController: OptionsViewController<Branches> = {
        createOptionsViewController(
            type: Branches.self,
            view: branchesWinchItemView,
            keyPath: \FormData.branches
        )
    }()

    private lazy var rolesViewController: OptionsViewController<Roles> = {
        createOptionViewController(
            type: Roles.self,
            view: roleWinchItemView,
            keyPath: \FormData.role
        )
    }()

    override func viewDidLoad() {
        super.viewDidLoad()
        // Setup is handled by protocols — clean and minimal!
    }
}

🔄 Switching Between the Two

Want to convert a screen from local to live or vice versa?
It’s just a matter of changing the protocol you conform to:

From:

class MyViewController: NibViewController, OptionsConfigurable { ... }

class MyViewController: NibViewController, APIOptionsConfigurable { ... }

With minimal changes to your setup logic — just provide apiPath, apiKey, and responseType, and you're good to go.

That’s how flexible and modular the architecture is. 💡

🪟 Paragraph 8: The Interface — OptionsViewController

At the core of this orchestration is the OptionsViewController<T>. This is the UI controller that renders the selectable items in a bottom sheet.

It’s generic over any MenuType — meaning it works for Roles, Cities, Branches, and anything else that conforms to our contract.

Core Responsibilities

Render hierarchical or flat options.
Support multi or single selection.
Handle search and filtering.
Display an empty view if needed.
Maintain selected state and sync with UI.
Call a completion handler with selected values.

Key Properties

public class OptionsViewController<T: MenuType>: NibViewController {
    var originalFilters = [SelectableMenuItem]()
    var filters = [SelectableMenuItem]()
    var selectedFilters: [OptionModel]?
    private let singleSelectionMode: Bool
    public let didSubmitSelectedFilters: (([OptionModel]) -> Void)
    public let hideNavigationBar: Bool
    public let enableSearch: Bool
    public let actionButtonTitle: String?
    ...
}

Each of these properties supports a concern:

originalFilters retains a reference to the unfiltered list.
filters is the currently displayed list (can change due to search).
selectedFilters tracks selected items.
singleSelectionMode toggles between radio-style and checkbox-style.
didSubmitSelectedFilters is our callback to the outside world.
actionButtonTitle customizes the save button text.

You pass the config from OptionsViewConfig, and this controller does all the work of:

Querying the MenuType
Rendering results
Handling taps
Updating models

It’s long. It’s powerful. It took weeks of tweaking.

But this story isn’t about UIKit. This is a Swift protocol love letter.

So we won’t show the full controller code here.

If you’re curious to explore the full implementation of OptionsViewController, feel free to reach out — I’m more than happy to share and connect.

📘 Paragraph 9: What We Can Improve

Even though this architecture has proven itself in real products, there's always room to evolve. Here are a few areas I believe can make it even more powerful:

Support SwiftUI: Everything here is built around UIKit. Creating a SwiftUI-compatible version of the OptionsViewController and the bottom sheet would bring this to the future of Apple development.
Support async/await: The current system uses closures for networking. Moving to Swift’s modern async syntax would improve readability, simplify error handling, and reduce nesting.
Enhanced Query Support: While we support injecting query dictionaries into the path, a more expressive query system—maybe even a DSL—would make filtering more powerful, readable, and safer.

These are the next steps I’m genuinely excited to explore. I hope someone reading this might build the SwiftUI version or suggest clever ways to inject async into the current pipeline.

🧠 Paragraph 10: What I Learned

Writing this system wasn’t just about code—it was about restraint. Knowing when not to overengineer, when to abstract, and how to communicate intent clearly through protocol names and method signatures.

It taught me:

That default behavior is powerful when designed right.
That protocols are like contracts—clear, flexible, and scalable.
That good architecture isn’t about cleverness, but about clarity.
That writing reusable, readable systems makes you a better teammate, not just a better coder.

And most importantly?

That even a boring form system… can be beautiful.

🧶 Conclusion — From Chaos to Craft**

Behind every line of this architecture lies a deeper story. I wasn’t always in Cairo, surrounded by Swift files and clean abstractions. I’m from Gaza. I left during the war, carrying more pain than luggage. I lost my home, my office, my quiet space to think—and found myself in a noisy, unfamiliar city with no friends, only loneliness and a borrowed laptop.

But I had code. And code gave me structure when the world didn’t.

This system, these protocols, this entire article—they weren’t just about UX polish. They were my way of reclaiming control, of building something elegant when everything else felt shattered.

And now I’m building more—my own framework: Bond, a modular way to structure Flutter apps with the same obsession for clarity you saw here.

If you’re building something and need architecture help, mentoring, or just want to chat code—I’m open to short consulting calls.

📩 Connect with me on LinkedIn

Follow my tech journey

🐦 Twitter/X: @salahamassi

📸 Instagram: @salahamassi

🐙 GitHub: salahamassi

Forem: Salah Nahed

Swift Protocol Magic II: Designing a Reusable Location Tracking System

The wishlist

Piece 1: LocationManager — the abstraction

Piece 2: TrackableLocationViewController — making any VC location-aware

Piece 3: LocationRestrictionConfigurable — the "you blocked us, now what?" protocol

Piece 4: AppLocationManager — the concrete glue

The init

The deliberate delay

The authorization switch — and the nested router fallback

The delegate methods

Why this design pays off

What I'd add next

Takeaways

Design-Driven Firebase in Flutter: Building Custom In-App Messaging with SwiftUI & Compose

🆕 Design-Driven Firebase in Flutter: Building Custom In-App Messaging with SwiftUI & Compose

Android Ain’t Easy: Crafting Custom FIAM with Compose

Setting Up Jetpack Compose: The First Brick in the Wall 🧱

🧨 Why version 1.4.8?

Replacing the Default: Building Our Custom In-App Renderer

🧠 The Heart of the Custom FIAM: NologyInAppMessageDisplay

🔍 Platform Differences: iOS vs Android

📸 Image Handling

🔗 Deep Linking

🧪 How to Test Custom In-App Messages

Step 1: Get the FID

Step 2: Send a Test Message

🔗 About Deep Links?

✅ Wrapping Up

🙋‍♂️ Who’s Behind This?

Swift Protocol Magic: Building a Beautiful, Reusable Option Selection System

🎨 Paragraph 1: The Artist’s Pain

🌱 Paragraph 2: The Root of Repetition

🚀 Paragraph 3: A Vision of Harmony

🛠️ Paragraph 4: The Craft — One Protocol to Rule Them All

The Protocol:

The Default Implementation:

🧱 OptionModel & SelectableModel

🧠 Real-World Customization: Cities.swift

🎬 Paragraph 6 – BaseOptionsConfigurable: One Interface, Two Destinies

🧪 The Render Flow (Extension Breakdown)

🧠 Let’s Understand the Parameters

🧰 OptionsViewConfig: The Behavior Controller

The Code:

What Each Property Does:

Example:

⚙️ Paragraph 7: Configurable Power — Local vs. Live

🧩 OptionsConfigurable

Protocol Definition:

Default Implementation:

Parameter Breakdown:

⚡️ APIOptionsConfigurable

Protocol Definition:

Default Implementation:

Parameter Breakdown:

👇 Example: AddBusinessUserViewController

🔄 Switching Between the Two

🪟 Paragraph 8: The Interface — OptionsViewController

Core Responsibilities

Key Properties

📘 Paragraph 9: What We Can Improve

🧠 Paragraph 10: What I Learned

🧶 Conclusion — From Chaos to Craft**

Piece 1: `LocationManager` — the abstraction

Piece 2: `TrackableLocationViewController` — making any VC location-aware

Piece 3: `LocationRestrictionConfigurable` — the "you blocked us, now what?" protocol

Piece 4: `AppLocationManager` — the concrete glue

🧨 Why version `1.4.8`?

🧠 The Heart of the Custom FIAM: `NologyInAppMessageDisplay`

🧠 Real-World Customization: `Cities.swift`

🧰 `OptionsViewConfig`: The Behavior Controller

🧩 `OptionsConfigurable`

⚡️ `APIOptionsConfigurable`

👇 Example: `AddBusinessUserViewController`