Using suggested searches with a search controller

At a glance

Project structure

Source bundle/
├── SuggestedSearch/
│   ├── ResultsTableController.swift
│   ├── MainTableViewController.swift
│   ├── AppDelegate.swift
│   ├── DetailViewController.swift
│   ├── SceneDelegate.swift
│   ├── Product.swift
│   ├── MainTableViewController+ResultsUpdate.swift
│   ├── MainTableViewController+SuggestedSearch.swift
│   └── Base.lproj/
│       └── LaunchScreen.storyboard
├── Configuration/
│   └── SampleCode.xcconfig
└── SuggestedSearch.xcodeproj/
    ├── .xcodesamplecode.plist
    └── project.pbxproj

Structure observations

• Search construction, presentation, and restoration belong to the primary controller rather than app lifecycle delegates.
• Results are a child adapter with their own table state, but product/filter authority remains with the primary controller.
• The local delegate carries two user intents—insert a token or open a product—without retaining the main controller.

Overall architecture

flowchart LR
    PRODUCTS["MainTableViewController products"] --> MAIN["MainTableViewController"]
    MAIN --> SEARCH["UISearchController"]
    SEARCH --> UPDATE["UISearchResultsUpdating callback"]
    UPDATE --> FILTER["Text and UISearchToken filter"]
    FILTER --> RESULTS["ResultsTableController"]
    RESULTS --> SUGGEST["Suggested rows or filtered products"]
    SUGGEST --> DELEGATE["SuggestedSearch weak delegate"]
    DELEGATE --> MAIN
    MAIN --> ACTIVITY["NSUserActivity search restoration"]

Reference code

SuggestedSearch/MainTableViewController.swift:101 — search-controller composition

        resultsTableController = ResultsTableController()
        resultsTableController.suggestedSearchDelegate = self

        searchController = UISearchController(
            searchResultsController: resultsTableController)
        searchController.searchResultsUpdater = self
        searchController.searchBar.delegate = self
        searchController.delegate = self
        navigationItem.searchController = searchController
        definesPresentationContext = true

Interpretation

The main controller is the search feature root. UIKit sends text/token changes through UISearchResultsUpdating; the controller filters its canonical products and assigns the projection to the results controller. Selection travels back as intent through a narrow local protocol.

Ownership and state

classDiagram
    MainTableViewController *-- ProductArray : products
    MainTableViewController *-- UISearchController : creates
    MainTableViewController *-- ResultsTableController : creates
    ResultsTableController *-- ProductArray : filteredProducts
    ResultsTableController o-- SuggestedSearch : weak delegate
    UISearchController o-- ResultsTableController : results content
    MainTableViewController *-- NSUserActivity : scene restoration state

Ownership evidence

SuggestedSearch/ResultsTableController.swift:19 — results projection and weak callback

class ResultsTableController: UITableViewController {
    var filteredProducts = [Product]()

    weak var suggestedSearchDelegate: SuggestedSearch?

    static let suggestedSearches = [
        NSLocalizedString("Red Flowers", comment: ""),
        NSLocalizedString("Green Flowers", comment: ""),
        NSLocalizedString("Blue Flowers", comment: "")
    ]
}

Composition denotes source-visible construction and retained value state. Aggregation denotes a stored or injected collaborator whose exclusive lifetime the source does not prove.

Class and protocol design

SuggestedSearch/ResultsTableController.swift:10 — local results-to-owner contract

protocol SuggestedSearch: AnyObject {
    func didSelectSuggestedSearch(token: UISearchToken)
    func didSelectProduct(product: Product)
}

class ResultsTableController: UITableViewController {
    weak var suggestedSearchDelegate: SuggestedSearch?
}

SuggestedSearch is the sample’s protocol-oriented seam: the results controller depends on two capabilities, not on MainTableViewController. UIKit search protocols handle framework events separately.

Access control

Reference code

SuggestedSearch/MainTableViewController.swift:17 — controller-private restoration schema

    private enum RestorationKeys: String {
        case searchControllerIsActive
        case searchBarText
        case searchBarIsFirstResponder
        case searchBarToken
    }

    var searchController: UISearchController!
    var resultsTableController: ResultsTableController!
    var products = [Product]()

Private nested keys protect the controller’s restoration encoding, while the three collaborator properties remain internal so same-module extensions can use them. No public, open, or fileprivate feature API is present.

Logic ownership and placement

Design patterns

Naming conventions

• Controller roles are explicit (MainTableViewController, ResultsTableController, DetailViewController).
• The local protocol names the interaction capability (SuggestedSearch); methods name emitted intents (didSelect...).
• Mode and projection names are descriptive (showSuggestedSearches, filteredProducts).
• Focused extensions are named for the conformance responsibility (ResultsUpdate, SuggestedSearch).

Architecture takeaways

• Let the primary controller own canonical products and search composition; keep the child as a results projection.
• Return token/product selection through a weak capability protocol rather than a concrete parent reference.
• Keep restoration keys private and collaborators internal when same-module extensions need them.

Source map

• Official Apple documentation