CalStorePageItemHandlerDelegate Protocol Reference

Conforms to	NSObject
Declared in	CalStorePageItemHandlerDelegate.h
Companion guide	OverridingDefaultActions

Overview

Delegate protocol for overriding behaviour in the standard UI classes.

The standard UI view controllers (CalStoreCalendarStoreViewController, CalStoreWeatherViewController, CalStoreStyledPageViewController, etc) perform default actions when a user interacted with a CalStorePageItem via their UI. For example, when a user taps on an already purchased item, a CalStoreInstallCalendarViewController will be created and presented to install the calendar via EventKit.

However, the default behaviour might not always be appropriate for apps. Some apps might want to install a calendar into their own system. CalStorePageItemHandlerDelegate makes it possible to override the default behaviour of these standard UI view controllers. This way, apps can take advantage of the UI that’s already present, but still perform custom actions.

Before invoking default behaviour after a user interacted with an item, pageItemHandlerDelegates get an opportunity to override that behavior on different levels: shouldHandleItem:withCallback: allows to override any interaction - shouldShowViewController:forItem:withCallback: allows to override showing view controllers, after the default behaviour has been performed - the other methods allow overriding specific behavior

Dynamically overriding

It’s possible to determine at runtime if you want to override behaviour: returning YES will make the view controller invoke default behaviour, returning NO will stop any actions by the view controller.

Showing Custom UIViewControllers

Custom implementations often want to show a custom view controller also. To do this, call the showViewControllerCallback() block with your custom view controller: showViewControllerCallback(yourViewController). The standard UI viewcontroller will make sure it gets presented or pushed, depending on the type. UINavigationController subclasses will be presented, while others might get pushed or presented.

Handling All Actions

`– shouldHandleItem:withCallback:`

Allows to override all actions for an item. When returning NO, no further action for this item will be performed. Default behavior calls further specialized delegates first, and then invoke specialized behavior.

- (BOOL)shouldHandleItem:(CalStorePageItem *)pageItem withCallback:(CalStorePageItemHandlerDelegateCallback)showViewControllerCallback

Parameters

`pageItem`	the pageItem that the user interacted with
`showViewControllerCallback`	call this block with your view controller as a parameter to let the UI class ‘show’ (present/push) your view controller

Return Value

YES to let the default behavior be performed, NO to stop performing any action for this item

Declared In

CalStorePageItemHandlerDelegate.h

`– shouldShowViewController:forItem:withCallback:`

Will be called before default behavior will show a view controller. Return NO to not show the view controller. Default behaviour let the UI class present/push the viewcontroller. UINavigationController (sub)classes will be presented, other view controllers will be pushed or presented.

- (BOOL)shouldShowViewController:(UIViewController *)viewController forItem:(CalStorePageItem *)pageItem withCallback:(CalStorePageItemHandlerDelegateCallback)showViewControllerCallback

Parameters

`viewController`	the viewController that got created by default behavior and will be shown
`pageItem`	the pageItem that the user interacted with
`showViewControllerCallback`	call this block with your view controller as a parameter to let the UI class ‘show’ (present/push) your view controller

Return Value

YES to let the default behavior be performed, NO to stop performing any action for this item

Discussion

Note: Will only be called for view controllers created by default behaviour, not when calling showViewControllerCallback(vc) in a delegate method.

Declared In

CalStorePageItemHandlerDelegate.h

Handling navigation

`– shouldNavigateToPageForItem:withCallback:`

Allows to override navigating to a page. Default behavior shows this page in a new viewcontroller pushed onto the stack.

- (BOOL)shouldNavigateToPageForItem:(CalStorePageItemPage *)pageItem withCallback:(CalStorePageItemHandlerDelegateCallback)showViewControllerCallback

Parameters

`pageItem`	the pageItem that the user interacted with
`showViewControllerCallback`	call this block with your view controller as a parameter to let the UI class ‘show’ (present/push) your view controller

Return Value

YES to let the default behavior be performed, NO to stop performing any action for this item

Declared In

CalStorePageItemHandlerDelegate.h

`– shouldNavigateToCalendarForItem:withCallback:`

Allows to override navigating to a calendar. Default behavior shows this calendar is a viewcontroller.

- (BOOL)shouldNavigateToCalendarForItem:(CalStorePageItemCalendar *)pageItem withCallback:(CalStorePageItemHandlerDelegateCallback)showViewControllerCallback

Parameters

`pageItem`	the pageItem that the user interacted with
`showViewControllerCallback`	call this block with your view controller as a parameter to let the UI class ‘show’ (present/push) your view controller

Return Value

YES to let the default behavior be performed, NO to stop performing any action for this item

Discussion

Note: Not yet implemented.

Declared In

CalStorePageItemHandlerDelegate.h

`– shouldNavigateToWeatherForItem:withCallback:`

Allows to override navigating to a weather calendar. Default behavior shows a CalStoreWeatherCalendarViewController.

- (BOOL)shouldNavigateToWeatherForItem:(CalStorePageItemParameterizedCalendar *)pageItem withCallback:(CalStorePageItemHandlerDelegateCallback)showViewControllerCallback

Parameters

`pageItem`	the pageItem that the user interacted with
`showViewControllerCallback`	call this block with your view controller as a parameter to let the UI class ‘show’ (present/push) your view controller

Return Value

YES to let the default behavior be performed, NO to stop performing any action for this item

Declared In

CalStorePageItemHandlerDelegate.h

`– shouldNavigateToWeatherCity:forItem:withCallback:`

Allows to override navigating to a city for a weather calendar. Default behavior shows a view controller for picking options and purchasing/installing this item for this city.

- (BOOL)shouldNavigateToWeatherCity:(CalStoreWeatherCity *)city forItem:(CalStorePageItemParameterizedCalendar *)pageItem withCallback:(CalStorePageItemHandlerDelegateCallback)showViewControllerCallback

Parameters

`city`	the city to navigate to
`pageItem`	the pageItem that the user interacted with
`showViewControllerCallback`	call this block with your view controller as a parameter to let the UI class ‘show’ (present/push) your view controller

Return Value

YES to let the default behavior be performed, NO to stop performing any action for this item

Declared In

CalStorePageItemHandlerDelegate.h

`– shouldNavigateToProductPageForItem:withCallback:`

Allows to override navigating to the product page for a purchasable item. Default behaviour shows a view controller with details about an in-app product.

- (BOOL)shouldNavigateToProductPageForItem:(CalStorePageItemPurchasable *)pageItem withCallback:(CalStorePageItemHandlerDelegateCallback)showViewControllerCallback

Parameters

`pageItem`	the pageItem that the user interacted with
`showViewControllerCallback`	call this block with your view controller as a parameter to let the UI class ‘show’ (present/push) your view controller

Return Value

YES to let the default behavior be performed, NO to stop performing any action for this item

Declared In

CalStorePageItemHandlerDelegate.h

`– shouldNavigateToPreviewForItem:withCallback:`

Allows to override navigating to the preview for a calendar item. Default behaviour shows a view controller that has a preview of the calendar’s content.

- (BOOL)shouldNavigateToPreviewForItem:(CalStorePageItemCalendar *)pageItem withCallback:(CalStorePageItemHandlerDelegateCallback)showViewControllerCallback

Parameters

`pageItem`	the pageItem that the user interacted with
`showViewControllerCallback`	call this block with your view controller as a parameter to let the UI class ‘show’ (present/push) your view controller

Return Value

YES to let the default behavior be performed, NO to stop performing any action for this item

Declared In

CalStorePageItemHandlerDelegate.h

Purchasing

`– shouldPurchaseItem:withCallback:`

Allows to override purchasing an item. Default behavior starts the purchase process, and when succeeded, will invoke behavior for installing the item, including the shouldInstall* delegate methods.

- (BOOL)shouldPurchaseItem:(CalStorePageItemPurchasable *)pageItem withCallback:(CalStorePageItemHandlerDelegateCallback)showViewControllerCallback

Parameters

`pageItem`	the pageItem that the user interacted with
`showViewControllerCallback`	call this block with your view controller as a parameter to let the UI class ‘show’ (present/push) your view controller

Return Value

YES to let the default behavior be performed, NO to stop performing any action for this item

Discussion

Note: When overriding, this method is responsible for also installing the item directly, if the purchase succeeds.

Declared In

CalStorePageItemHandlerDelegate.h

`– shouldInstallCalendarForItem:withCallback:`

Allows to override installing a calendar. Default behavior shows a CalStoreInstallCalendarViewController that uses EventKit to install the calendar.

- (BOOL)shouldInstallCalendarForItem:(CalStorePageItemCalendar *)pageItem withCallback:(CalStorePageItemHandlerDelegateCallback)showViewControllerCallback

Parameters

`pageItem`	the pageItem that the user interacted with
`showViewControllerCallback`	call this block with your view controller as a parameter to let the UI class ‘show’ (present/push) your view controller

Return Value

YES to let the default behavior be performed, NO to stop performing any action for this item

Declared In

CalStorePageItemHandlerDelegate.h

`– shouldInstallOrPurchaseCalendarForItem:withCallback:`

Allows to override installing or purchasing a calendar. Default behavior starts the flow indicated by shouldPurchaseItem:withCallback: for items not purchased; for purchased items, the flow of shouldInstallCalendarForItem:withCallback: is initiated.

- (BOOL)shouldInstallOrPurchaseCalendarForItem:(CalStorePageItemCalendar *)pageItem withCallback:(CalStorePageItemHandlerDelegateCallback)showViewControllerCallback

Parameters

`pageItem`	the pageItem that the user interacted with
`showViewControllerCallback`	call this block with your view controller as a parameter to let the UI class ‘show’ (present/push) your view controller

Return Value

YES to let the default behavior be performed, NO to stop performing any action for this item

Declared In

CalStorePageItemHandlerDelegate.h

`– shouldHandleBeingPurchasedForItem:withCallback:`

Allows to override the action performed for an item when it is being purchased. Default behavior does nothing.

- (BOOL)shouldHandleBeingPurchasedForItem:(CalStorePageItemPurchasable *)pageItem withCallback:(CalStorePageItemHandlerDelegateCallback)showViewControllerCallback

Parameters

`pageItem`	the pageItem that the user interacted with
`showViewControllerCallback`	call this block with your view controller as a parameter to let the UI class ‘show’ (present/push) your view controller

Return Value

YES to let the default behavior be performed, NO to stop performing any action for this item

Declared In

CalStorePageItemHandlerDelegate.h

`– shouldHandleInstalledCalendarForItem:withCallback:`

Allows to override the action performed for a calendar when it is already installed. Default behavior does nothing.

- (BOOL)shouldHandleInstalledCalendarForItem:(CalStorePageItemCalendar *)pageItem withCallback:(CalStorePageItemHandlerDelegateCallback)showViewControllerCallback

Parameters

`pageItem`	the pageItem that the user interacted with
`showViewControllerCallback`	call this block with your view controller as a parameter to let the UI class ‘show’ (present/push) your view controller

Return Value

YES to let the default behavior be performed, NO to stop performing any action for this item

Declared In

CalStorePageItemHandlerDelegate.h

`– shouldHandleSucceededCalendarInstallationForItem:withCallback:`

Allows to override the action performed for a calendar when it’s installation succeeded. Default behavior does nothing.

- (BOOL)shouldHandleSucceededCalendarInstallationForItem:(CalStorePageItemCalendar *)pageItem withCallback:(CalStorePageItemHandlerDelegateCallback)showViewControllerCallback

Parameters

`pageItem`	the pageItem that the user interacted with
`showViewControllerCallback`	call this block with your view controller as a parameter to let the UI class ‘show’ (present/push) your view controller

Return Value

YES to let the default behavior be performed, NO to stop performing any action for this item

Declared In

CalStorePageItemHandlerDelegate.h

`– shouldInstallPageForItem:withCallback:`

Allows to override installing a page (some pages are purchasable). Default behavior navigates to the page, presented modally inside a UINavigationController.

- (BOOL)shouldInstallPageForItem:(CalStorePageItemPage *)pageItem withCallback:(CalStorePageItemHandlerDelegateCallback)showViewControllerCallback

Parameters

`pageItem`	the pageItem that the user interacted with
`showViewControllerCallback`	call this block with your view controller as a parameter to let the UI class ‘show’ (present/push) your view controller

Return Value

YES to let the default behavior be performed, NO to stop performing any action for this item

Discussion

Note: Not yet implemented.

Declared In

CalStorePageItemHandlerDelegate.h