DFImageManager: An Objective-C repository from kean

Advanced framework for loading, caching, processing, displaying and preheating images.

This framework is no longer maintained.

Programming in Swift? Check out Nuke!

Features

Zero config
Works great with both Objective-C and Swift
Performant, asynchronous, thread safe

Loading

Uses NSURLSession with HTTP/2 support
Optional AFNetworking integration, combine the power of both frameworks!
Uses a single fetch operation for equivalent requests
Intelligent preheating of images close to the viewport

Caching

Doesn't reinvent caching, relies on HTTP cache and its implementation in Foundation
Caching is completely transparent to the client
Two cache layers, including top level memory cache for decompressed images

Processing

Optional FLAnimatedImage integration
Optional WebP integration
Progressive image decoding including progressive JPEG
Background image decompression and scaling in a single step
Resize and crop loaded images to fit displayed size, add rounded corners or circle

Advanced

Customize different parts of the framework using dependency injection
Create and compose image managers into a tree of responsibility

Getting Started

Take a look at comprehensive demo using pod try DFImageManager command
Check out complete documentation and Wiki
Install, @import DFImageManager and enjoy!

Usage

Zero Config

[[DFImageManager imageTaskForResource:<#imageURL#> completion:^(UIImage *image, NSError *error, DFImageResponse *response, DFImageTask *task){
    // Use loaded image
}] resume];

Adding Request Options

DFMutableImageRequestOptions *options = [DFMutableImageRequestOptions new]; // builder
options.priority = DFImageRequestPriorityHigh;
options.allowsClipping = YES;

DFImageRequest *request = [DFImageRequest requestWithResource:<#imageURL#> targetSize:CGSizeMake(100, 100) contentMode:DFImageContentModeAspectFill options:options.options];

[[DFImageManager imageTaskForRequest:request completion:^(UIImage *image, NSError *error, DFImageResponse *response, DFImageTask *imageTask) {
    // Image is resized and clipped to fill 100x100px square
    if (response.isFastResponse) {
        // Image was returned synchronously from the memory cache
    }
}] resume];

Using Image Task

DFImageTask *task = [DFImageManager imageTaskForResource:<#imageURL#> completion:nil];
NSProgress *progress = task.progress;
task.priority = DFImageRequestPriorityHigh; // Change priority of executing task
[task cancel];

Using UI Components

Use methods from UIImageView category for simple cases:

UIImageView *imageView = ...;
[imageView df_setImageWithResource:<#imageURL#>];

Use DFImageView for more advanced features:

DFImageView *imageView = ...;
imageView.allowsAnimations = YES; // Animates images when the response wasn't fast enough
imageView.managesRequestPriorities = YES; // Automatically changes current request priority when image view gets added/removed from the window

[imageView prepareForReuse];
[imageView setImageWithResource:<#imageURL#>];

UICollectionView

- (UICollectionViewCell *)collectionView:(UICollectionView *)collectionView cellForItemAtIndexPath:(NSIndexPath *)indexPath {
    UICollectionViewCell *cell = <#cell#>
    DFImageView *imageView = (id)[cell viewWithTag:15];
    if (!imageView) {
        imageView = [[DFImageView alloc] initWithFrame:cell.bounds];
        imageView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
        imageView.tag = 15;
        [cell addSubview:imageView];
    }
    [imageView prepareForReuse];
    [imageView setImageWithResource:<#image_url#>];
    return cell;
}

Cancel image task as soon as the cell goes offscreen (optional):

- (void)collectionView:(UICollectionView *)collectionView didEndDisplayingCell:(UICollectionViewCell *)cell forItemAtIndexPath:(NSIndexPath *)indexPath {
    [((DFImageView *)[cell viewWithTag:15]) prepareForReuse];
}

Preheating Images

NSArray<DFImageRequest *> *requestsForAddedItems = <#requests#>;
[DFImageManager startPreheatingImagesForRequests:requestsForAddedItems];

NSArray<DFImageRequest *> *requestsForRemovedItems = <#requests#>;
[DFImageManager stopPreheatingImagesForRequests:requestsForRemovedItems];

Progressive Image Decoding

// Enable progressive image decoding
[DFImageManagerConfiguration setAllowsProgressiveImage:YES];

// Create image request that allows progressive image
DFMutableImageRequestOptions *options = [DFMutableImageRequestOptions new];
options.allowsProgressiveImage = YES;
DFImageRequest *request = <#request#>;

DFImageTask *task = <#task#>;
task.progressiveImageHandler = ^(UIImage *__nonnull image){
    imageView.image = image;
};
[task resume];

Customizing Image Manager

id<DFImageFetching> fetcher = <#fetcher#>;
id<DFImageDecoding> decoder = <#decoder#>;
id<DFImageProcessing> processor = <#processor#>;
id<DFImageCaching> cache = <#cache#>;

DFImageManagerConfiguration *configuration = [[DFImageManagerConfiguration alloc] initWithFetcher:fetcher];
configuration.decoder = decoder;
configuration.processor = processor;
configuration.cache = cache;

[DFImageManager setSharedManager:[[DFImageManager alloc] initWithConfiguration:configuration]];

Composing Image Managers

The DFCompositeImageManager constructs a tree of responsibility from image managers and dynamically dispatch requests between them. Each manager should conform to DFImageManaging protocol. The DFCompositeImageManager also conforms to DFImageManaging protocol so that individual managers and compositions can be treated uniformly.

id<DFImageManaging> manager1 = <#manager#>
id<DFImageManaging> manager2 = <#manager#>
id<DFImageManaging> composite = [[DFCompositeImageManager alloc] initWithImageManagers:@[manager1, manager2]];

Design

Protocol	Description
`DFImageManaging`	A high-level API for loading images
`DFImageFetching`	Performs fetching of image data (`NSData`)
`DFImageDecoding`	Converts `NSData` to `UIImage` objects
`DFImageProcessing`	Processes decoded images
`DFImageCaching`	Stores processed images into memory cache

Installation

CocoaPods

To install DFImageManager add a dependency in your Podfile:

pod 'DFImageManager'

By default it will install these subspecs:

DFImageManager/Core - DFImageManager core classes
DFImageManager/UI - UI components

There are four more optional subspecs:

DFImageManager/AFNetworking - replaces networking stack with AFNetworking
DFImageManager/GIF - GIF support with a FLAnimatedImage dependency
DFImageManager/WebP - WebP support with a libwebp dependency
DFImageManager/PhotosKit - Photos Framework support

To install optional subspecs include them in your Podfile:

pod 'DFImageManager'
pod 'DFImageManager/AFNetworking'
pod 'DFImageManager/GIF'
pod 'DFImageManager/WebP'
pod 'DFImageManager/PhotosKit'

Carthage

DFImageManager has a limited Carthage support that doesn't feature FLAnimatedImage and AFNetworking integration. To install DFImageManager add a dependency to your Cartfile:

github "kean/DFImageManager"

Requirements

iOS 8.0+ / watchOS 2
Xcode 7.0+

Supported Image Formats

Image formats supported by UIImage (JPEG, PNG, BMP, and more)
GIF (GIF subspec)
WebP (WebP subspec)

Contribution

If you need help, use Stack Overflow. (Tag 'dfimagemanager')
If you found a bug, and can provide steps to reproduce it, open an issue.
If you have a feature request, open an issue.
If you want to contribute, branch of the develop branch and submit a pull request.

Contacts

License

DFImageManager is available under the MIT license. See the LICENSE file for more info.