How To Use SDWebImage

Web Image

This library provides a category for UIImageVIew with support for remote images coming from the web.

It provides:

• An UIImageView category adding web image and cache management to the Cocoa Touch framework
• An asynchronous image downloader
• An asynchronous memory + disk image caching with automatic cache expiration handling
• A guarantee that the same URL won't be downloaded several times
• A guarantee that bogus URLs won't be retried again and again
• Performances!

• How To Use It

  Using UIImageView+WebCache category with UITableView

  Just #import the UIImageView+WebCache.h header, and call the setImageWithURL:placeholderImage: method from the tableView:cellForRowAtIndexPath: UITableViewDataSource method. Everything will be handled for you, from async downloads to caching management.

  #import "UIImageView+WebCache.h"
  
  ...
  
  - (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
  {
      static NSString *MyIdentifier = @"MyIdentifier";
  
      UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:MyIdentifier];
  
      if (cell == nil)
      {
          cell = [[[UITableViewCell alloc] initWithStyle:UITableViewCellStyleDefault
                                         reuseIdentifier:MyIdentifier] autorelease];
      }
  
      // Here we use the new provided setImageWithURL: method to load the web image
      [cell.imageView setImageWithURL:[NSURL URLWithString:@"http://www.domain.com/path/to/image.jpg"]
                     placeholderImage:[UIImage imageNamed:@"placeholder.png"]];
  
      cell.textLabel.text = @"My Text";
      return cell;
  }
  

  Using SDWebImageManager

  The SDWebImageManager is the class behind the UIImageView+WebCache category. It ties the asynchronous downloader with the image cache store. You can use this class directly to benefit from web image downloading with caching in another context than a UIView (ie: with Cocoa).

  Here is a simple example of how to use SDWebImageManager:

  SDWebImageManager *manager = [SDWebImageManager sharedManager];
  
  UIImage *cachedImage = [manager imageWithURL:url];
  
  if (cachedImage)
  {
      // Use the cached image immediatly
  }
  else
  {
      // Start an async download
      [manager downloadWithURL:url delegate:self];
  }
  

  Your class will have to implement the SDWebImageManagerDelegate protocol, and to implement the webImageManager:didFinishWithImage: method from this protocol:

  - (void)webImageManager:(SDWebImageManager *)imageManager didFinishWithImage:(UIImage *)image
  {
      // Do something with the downloaded image
  }
  

  Using Asynchronous Image Downloader Independently

  It is possible to use the async image downloader independently. You just have to create an instance of SDWebImageDownloader using its convenience constructor downloaderWithURL:delegate:.

  downloader = [SDWebImageDownloader downloaderWithURL:url delegate:self];
  

  The download will start immediately and the imageDownloader:didFinishWithImage: method from the SDWebImageDownloaderDelegate protocol will be called as soon as the download of image is completed.

  Using Asynchronous Image Caching Independently

  It is also possible to use the NSOperation based image cache store independently. SDImageCache maintains a memory cache and an optional disk cache. Disk cache write operations are performed asynchronous so it doesn't add unnecessary latency to the UI.

  The SDImageCache class provides a singleton instance for convenience but you can create your own instance if you want to create separated cache namespace.

  To lookup the cache, you use the imageForKey: method. If the method returns nil, it means the cache doesn't currently own the image. You are thus responsible for generating and caching it. The cache key is an application unique identifier for the image to cache. It is generally the absolute URL of the image.

  UIImage *myCachedImage = [[SDImageCache sharedImageCache] imageFromKey:myCacheKey];
  

  By default SDImageCache will lookup the disk cache if an image can't be found in the memory cache. You can prevent this from happening by calling the alternative method imageFromKey:fromDisk: with a negative second argument.

  To store an image into the cache, you use the storeImage:forKey: method:

  [[SDImageCache sharedImageCache] storeImage:myImage forKey:myCacheKey];
  

  By default, the image will be stored in memory cache as well as on disk cache (asynchronously). If you want only the memory cache, use the alternative method storeImage:forKey:toDisk: with a negative third argument.

  Future Enhancements

  • LRU memory cache cleanup instead of reset on memory warning