saurabhj80/MapleBacon

MapleBacon is a Swift image download and caching library.

Requirements

iOS 8.0+
Xcode 6.3

Installation

The easiest way is either through CocoaPods. Simply add the dependency to your Podfile and then pod install:

pod `MapleBacon`

or Carthage. Add the following to your Cartfile and then run carthage update:

github "zalando/MapleBacon"

If you don't like any of those options, you can add the dependency as a git submdoule:

Add MapleBacon as a git submodule: open your project directory in the Terminal and git submodule add https://github.com/zalando/MapleBacon.git
Open the resulting MapleBacon directory and drag the Library/MapleBacon/MapleBacon.xcodeproj file into your Xcode project
In the "Build Phases" tab add MapleBacon as target dependency
Add a "New Copy Files Phase" and rename it to "Copy Frameworks". In the "Destination" dropdown select "Frameworks" and add "MapleBacon.framework" in the list of files to copy.

Using MapleBacon

Downloading an image

The most straightforward way is the UIImageView extension:

import MapleBacon

…

if let imageURL = NSURL(string: "…") {
	imageView.setImageWithURL(imageURL)
}

or with an optional closure, if you want to check for a possible error:

if let imageURL = NSURL(string: "…") {
	imageView.setImageWithURL(imageURL) { (instance, error) in
		…
	}
}

Using the ImageManager directly

You can also access the underlying handler directly for more advanced usage:

if let imageURL = NSURL(string: "…") {
	let manager = ImageManager.sharedManager
	
	manager.downloadImageAtURL(imageURL, completion: { (imageInstance, error) in
		…
	})
}

Scaling images

For the quality conscious among you, MapleBacon also allows for more advanced (and more expensive) scaling of downloaded images. Under the hood this uses Core Graphics. The simplest way to use this mode is to pass in a cacheScaled: true Bool into the UIImageView extension:

imageView.setImageWithURL(imageURL, cacheScaled: true)

// Or the call back way
imageView.setImageWithURL(imageURL, cacheScaled: true) { (imageInstance, error) in
…
}

This will cache the scaled version of the image in the background, so the whole computation is done only once. It respects both the size and contentMode of the imageView that you call this method on.

Alternatively, you can also access the Resizer class directly (and use it independently of downloading images).

Caching

MapleBacon will cache your images both in memory and on disk. Disk storage is automatically pruned after a week but you can control the maximum cache time yourself too:

let maxAgeOneDay: NSTimeInterval = 60 * 60 * 24
DiskStorage.sharedStorage.maxAge = maxAgeOneDay

You can also wipe the storage completely:

MapleBaconStorage.sharedStorage.clearStorage()

Or, should the app come under memory pressure, clear the in memory images only:

override func didReceiveMemoryWarning() {
	MapleBaconStorage.sharedStorage.clearMemoryStorage()
}

MapleBacon supports multiple cache regions:

let storage = DiskStorage(name: "…")

This requires a little more effort on your end. In this case you'll need to use the ImageManager directly as described above and inject your custom storage instance there:

let storage = DiskStorage(name: "…")

if let imageURL = NSURL(string: "…") {
	ImageManager.sharedManager.downloadImageAtURL(imageURL, storage: storage) {
		(imageInstance: ImageInstance?, error: NSError?) in
		…
	}
}

Contributors

Acknowledgements

Resize a UIImage the right way

Misc

Find out a bit more on how MapleBacon came to be on the Zalando Tech Blog

Licence

MapleBacon is released under the MIT license. See LICENSE for details

saurabhj80 / MapleBacon