App Intents: Grouping Parent Parameters Using a Unified Entity Approach

From Quentin Zervaas, developer of Streaks, on their blog Crunchy Bagel in a post titled “Migrating Widget Configurations with Parent Parameters to use AppIntent”:

In order to model this in an App Entity using parameterSummary, we would then need a different summary for every task type (“automatic”, “specific”, “next on page”, “next in category”), as well as accounting for each chart type. This is 8 combinations.

Now consider another of our widgets: the “Tasks” widget. This lets you choose up to 4 different tasks, and has the same options:

In this case, there would be 16 combinations, which really doesn’t scale well. It’s extremely hard to maintain and is inflexible if future changes are needed.

To solve this, I introduced a new type called TaskTypeAppEntity, which encapsulates the four different types (automatic, specific, next on page, next in category) in a single entity:

struct TaskTypeAppEntity: AppEntity, Identifiable {
    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Task Type"

    let id: TaskTypeAppEntityIdentifier

    var title: String

    var displayRepresentation: DisplayRepresentation {
        .init(title: .init(stringLiteral: title))
    }

    static let defaultQuery = TaskTypeAppEntityQuery()
}

enum TaskTypeAppEntityIdentifier {
    case automatic
    case task(TaskID)
    case category(CategoryID)
    case page(PageID)
}

When building the defaultQuery, it’s just a case of including all of the options in that query. You can even group it into separate sections:

This is more code than I’ve probably ever shared on my site, but this method is incredible for apps with more complex data models to build a clean App Intents experience for their users – all App Intents developers should take a look and see if they can use this.

I’ll definitely be recommending this to my clients – I had to save this here on my blog, as well as rewrite my own headline to clarify that this is useful beyond widget configurations as well as beyond moving from “INIntents” to App Intents.

View the original, see Quentin’s post, and get Streaks on the App Store.