Providing Placeholder Complications
When your users are adding complications to their watch face, they’ll see your app by name in the list, sorted alphabetically, as they scroll through the list of supported complications from their apps. On the watch face itself, however, they’ll see some placeholder content instead of real content. This is deliberate—notice that while you’re configuring the watch face, it sets its time to 10:09, another nod to traditional watchmaking. In the same way, complication placeholder content represents the typical content of a complication, not necessarily its actual content. It’s a chance for you to show your users what the complication is all about, so you should put your best face forward.
The method you’ll implement in your ComplicationController class is getPlaceholderTemplateForComplication(_:withHandler:). Instead of being called when the user is actively selecting his complications, the placeholder you create is aggressively cached. watchOS will call this method when your app is installed so that by the time the user wants to choose a complication, the placeholder is already up to date. This means, then, that you can’t rely on any user data to create the placeholder template, since the app will not have run to ask them for permission. You’ll just use the generic calendar template for when there are no food events. Unlike the other methods, you don’t return a CLKComplicationTimelineEntry here; since you don’t need to provide an NSDate for the timeline entry’s time, you simply return a CLKComplicationTemplate:
| | func getPlaceholderTemplateForComplication(complication: CLKComplication, |
| | withHandler handler: (CLKComplicationTemplate?) -> Void) { |
| | switch complication.family { |
| | case .ModularLarge: |
| | handler(modularLargeTimelineEntryForNoEvents().complicationTemplate) |
| | case .UtilitarianLarge: |
| | handler( |
| | utilitarianLargeTimelineEntryForNoEvents().complicationTemplate) |
| | default: |
| | handler(nil) |
| | } |
| | } |
You can leverage your existing methods and pull out the complicationTemplate property to provide a template. Now that you’ve done this, you can see your templates in action. Simply choose a different complication, return to the watch face, and then go back to the list of complications. When you scroll to your app, you’ll see the template instead of real data! Now your users will be able to see your complication before they commit to using it in one of their scarce complication slots, as the following figure shows. Next up, let’s look at how to restrict which watch faces your complication appears on, so that you can avoid someone trying to install it on a watch face you don’t support.
Figure 5. Our complication placeholder in the watch face configuration screen