Extending Image Manager Guide

Composing Image Managers

The DFCompositeImageManager is a class that allows clients to construct a tree structure from multiple image managers. Each image manager should conform to DFImageManaging protocol. The DFCompositeImageManager also conforms to DFImageManaging protocol, which lets clients treat individual objects and compositions uniformly. The DFCompositeImageManager is initialized with an array of image managers, each manager in the array can also be a composite.

The tree constructed by DFCompositeImageManager is a tree of responsibility. Each image manager added to the composite defines which image requests it can handle by implementing -(BOOL)canHandleRequest:(DFImageRequest *)request method from DFImageManaging protocol. The DFCompositeImageManager dynamically dispatches image requests between manages. It starts with the first manager added to the composite. If the first manager can't handle the request it is passes to the next one and so on.

The DFImageManager class provides a default image manager that contains all built in managers: the ones that support NSURL fetching, PHAsset objects, etc. This default manager is set as a [DFImageManager sharedManager]. It's easy for clients to add additional managers to the shared manager. Those manages can either support new image requests, not handled by the framework, or intercept requests handled by existing managers.

Here's an example of how you may add an image manager with a customized DFURLImageFetcher:

DFURLImageFetcher *URLImageFetcher = /* Create and customize your own URL image fetcher. */
id<DFImageManaging> URLImageManager = [[DFImageManager alloc] initWithConfiguration:[DFImageManagerConfiguration configurationWithFetcher:URLImageFetcher /* Create configuration */ ]];
    
// Construct a chain of image managers with you manager at the beginning
NSArray *managers = @[ URLImageManager, [DFImageManager sharedManager] ];
id<DFImageManaging> composite = [[DFCompositeImageManager alloc] initWithImageManagers:managers]; 
[DFImageManager setSharedManager:composite];

For more info on customizing DFURLImageFetcher see documentation. There are ways to customize almost everything.

Adding Support for Custom URL Protocol

The DFURLImageFetcher class is built using Foundation URL Loading System. The URL loading system natively supports the http, https, file, ftp, and data protocols. It also allows clients to extend the number of the supported protocols and to provide their own implementation of natively supported protocols. This functionality is often used by libraries like OHHTTPStubs that are designed to stub network requests for your unit tests.

There are many existing tutorials on the web on how to implement and register your custom URL protocol (subclass of abstract NSURLProtocol class). There are no other steps required to make those protocols available in DFURLImageFetcher. However if you are using a DFCompositeImageManager you should also make sure that the URL scheme supported by your custom protocol is added to the supportedSchemes set of the DFURLImageFetcher. The set is used when DFURLImageFetcher determines whether is can handle image request (DFImageRequest) or not.