Imaginary
Table of Contents
Description
Using remote images in an application is more or less a requirement these days. This process should be easy, straight-forward and hassle free, and with Imaginary, it is. The library comes with a narrow yet flexible public API and a bunch of built-in unicorny features:
- Asynchronous image downloading
- Memory and disk cache based on Cache
- Image decompression
- Default transition animations
- Possibility to pre-process and modify the original image
- Works on any view, including
ImageView,Button, ... - Supports iOS, tvOS, macOS
Usage
In the most common case, you want to set remote image from url onto ImageView. Imaginary does the heavy job of downloading and caching images. The caching is done via 2 cache layers (memory and disk) to allow fast retrieval. It also manages expiry for you. And the good news is that you can customise most of these features.
Basic
Set image with URL
Simply pass URL to fetch.
let imageUrl = URL(string: "https://avatars2.githubusercontent.com/u/1340892?v=3&s=200")
imageView.setImage(url: imageUrl)
Use placeholder
Placeholder is optional. But the users would be much pleased if they see something while images are being fetched.
let placeholder = UIImage(named: "PlaceholderImage")
let imageUrl = URL(string: "https://avatars2.githubusercontent.com/u/1340892?v=3&s=200")
imageView.setImage(url: imageUrl, placeholder: placeholder)
Use callback for when the image is fetched
If you want to get more info on the fetching result, you can pass a closure as completion.
imageView.setImage(url: imageUrl) { result in
switch result {
case .value(let image):
print(image)
case .error(let error):
print(error)
}
}
result is an enum Result that let you know if the operation succeeded or failed. The possible error is of ImaginaryError.
Advanced
Passing option
You can also pass Option when fetching images; it allows fine grain control over the fetching process. Option defaults to no pre-processor and a displayer for ImageView.
let option = Option()
imageView.setImage(url: imageUrl, option: option)
Pre-processing
Images are fetched, decompressed and pre-processed in the background. If you want to modify, simply implement your own ImageProcessor and specify it in the Option. The pre-processing is done in the background, before the image is set into view.
public protocol ImageProcessor {
func process(image: Image) -> Image
}
This is how you apply tint color before setting images.
let option = Option(imagePreprocessor: TintImageProcessor(tintColor: .orange))
imageView.setImage(url: imageUrl, option: option)
Imaginary provides the following built in pre-processors
-
TintImageProcessor: apply tint color using color blend effect -
ResizeImageProcessor: resize -
RoundImageProcessor: make round corner
Displaying
Imaginary supports any View, it can be UIImageView, UIButton, MKAnnotationView, UINavigationBar, ... As you can see, the fetching is the same, the difference is the way the image is displayed. To avoid code duplication, Imaginary take advantages of Swift protocols to allow fully customisation.
You can roll out your own displayer by comforming to ImageDisplayer and specify that in Option
public protocol ImageDisplayer {
func display(placeholder: Image, onto view: View)
func display(image: Image, onto view: View)
}
This is how you set an image for UIButton
let option = Option(imageDisplayer: ButtonDisplayer())
button.setImage(url: imageUrl, option: option)
let option = Option(imageDisplayer: ImageDisplayer(animationOption: .transitionCurlUp))
imageView.setImage(url: imageUrl, option: option)
These are the buit in displayers. You need to supply the correct displayer for your view
- ImageDisplayer: display onto
UI|NSImageView. This is the default with cross dissolve animation. - ButtonDisplayer: display onto
UI|NSButtonusingsetImage(_ image: UIImage?, for state: UIControlState) - ButtonBackgroundDisplayer: display onto
UI|NSButtonusingsetBackgroundImage(_ image: UIImage?, for state: UIControlState)
Downloading
Imaginary uses ImageFetcher under the hood, which has downloader and storage. You can specify your own ImageDownloader together with a modifyRequest closure, there you can change request body or add more HTTP headers.
var option = Option()
option.downloaderMaker = {
return ImageDownloader(modifyRequest: {
var request = $0
request.addValue("Bearer 123", forHTTPHeaderField: "Authorization")
return request
})
}
imageView.setImage(imageUrl, option: option)
Caching
The storage defaults to Configuration.storage, but you can use your own Storage, this allows you to group saved images for particular feature. What if you want forced downloading and ignore storage? Then simply return nil. For how to configure storage, see Storage
var option = Option()
option.storageMaker = {
return Configuration.imageStorage
}
Configuration
You can customise the overal experience with Imaginary through Configuration.
trackBytesDownloaded: track how many bytes have been used to download a specific imagetrackError: track if any error occured when fetching an image.imageStorage: the storage used by all fetching operations.
ImageFetcher
Imaginary uses ImageFetcher under the hood. But you can use it as a standalone component.
ImageDownloader
Its main task is to download image and perform all kinds of sanity checkings.
let downloader = ImageDownloader()
downloader.download(url: imageUrl) { result in
// handle result
}
ImageFetcher
This knows how to fetch and cache the images. It first checks memory and disk cache to see if there's image. If there isn't it will perform network download. You can optionally ignore the cache by setting storage to nil.
let fetcher = ImageFetcher(downloader: ImageDownloader(), storage: myStorage()
fetcher.fetch(url: imageUrl) { result in
// handle result
}
MultipleImageFetcher
It sometimes makes sense to pre download images beforehand to improve user experience. We have MultipleImageFetcher for you
let multipleFetcher = MultipleImageFetcher(fetcherMaker: {
return ImageFetcher()
})
multipleFetcher.fetch(urls: imageUrls, each: { result in
// handle when each image is fetched
}, completion: {
// handle when all images are fetched
})
This is ideal for the new prefetching mode in UICollectionView
Installation
Imaginary is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod 'Imaginary'
Imaginary is also available through Carthage. To install just write into your Cartfile:
github "hyperoslo/Imaginary"
Imaginary can also be installed manually. Just download and drop Sources folders in your project.
Author
Hyper Interaktiv AS, [email protected]
License
Imaginary is available under the MIT license. See the LICENSE file for more info.
45 Dec 2, 2022
0 Jan 23, 2022
44 Nov 20, 2022
99 Aug 27, 2021
222 Dec 17, 2022
28 Oct 28, 2022
4 Oct 19, 2022
601 Dec 26, 2022
2.1k Dec 30, 2022
5.2k Dec 11, 2022
8.3k Jan 5, 2023
72 Sep 19, 2022
4 Dec 31, 2021
41 Nov 28, 2022
11 Oct 19, 2022
319 Jan 7, 2023
113 Nov 28, 2022
2 Mar 1, 2022