carrierwave-ios

carrierwave-ios is easy to use iOS library which provides flexible way to download, upload and edit asset files. Designed to integrate with CarrierWave ruby gem, makes your work as fast as possible.

Features:

carrierwave-ios handles:

• download and upload assets
• edit image assets
• image compression

Requirements

• Xcode 6.0 with iOS 8.0 SDK
• Carthage 0.5
• CocoaPods 0.36.0.rc.1 (use sudo gem install cocoapods --pre to grab it!)

CocoaPods

CocoaPods is a dependency manager for Objective-C, which automates and simplifies the process of using 3rd-party. To use carrierwave-ios via CocoaPods write in your Podfile:

pod 'Carrierwave', '~> 0.1.0'

Configuration

Just add @import Carrierwave in your source file whenever you want to use carrierwave-ios.

To connect carrierwave-ios with rails backend, you just need to set serverURL property in [CRVNetworkManager sharedManager] to your backend server url. We are recommending to make this in application:didFinishLaunchingWithOptions: method in your AppDelegate class.

Usage

CRVNetworkManager encapsulates the common tasks, including upload, download and delete asset. All supported assets should be wrapped with usage of CRVAssetType protocol.

Upload tasks

Declarations:

- (NSString *)uploadAsset:(id<CRVAssetType>)asset progress:(CRVProgressBlock)progress completion:(CRVUploadCompletionBlock)completion;
- (NSString *)uploadAsset:(id<CRVAssetType>)asset toURL:(NSURL *)url progress:(CRVProgressBlock)progress completion:(CRVUploadCompletionBlock)completion;

Creating an upload proccess:

NSString *proccessId;
proccessId = [[CRVNetworkManager sharedManager] uploadAsset:asset progress:^(double progress) {
	NSLog(@"Progress: %f", progress);
} completion:^(CRVUploadInfo *info, NSError *error) {
	if (error) {
    	NSLog(@"Error: %@", error);
    } else {
    	NSLog(@"Success: %@", info);
	}                  
}]

If upload finishes with success, method will return CRVUploadInfo object that wraps assetIdentifier of uploaded asset and server side path to it, stored in assetPath property. For dynamic server urls please use uploadAsset:toURL:progress:completion method.

Download task

Declarations:

- (NSString *)downloadAssetWithIdentifier:(NSString *)identifier progress:(CRVProgressBlock)progress completion:(CRVDownloadCompletionBlock)completion;
- (NSString *)downloadAssetFromURL:(NSURL *)url progress:(CRVProgressBlock)progress completion:(CRVDownloadCompletionBlock)completion;

Creating a download proccess:

NSString *proccessId
proccessId = [[CRVNetworkManager sharedManager] downloadAssetWithIdentifier:identifier progress:^(double progress) {
	NSLog(@"Progress: %f", progress);
} completion:^(CRVImageAsset *asset, NSError *error) {
	if (error) {
    	NSLog(@"Error: %@", error);
    } else {
    	NSLog(@"Success");
	}
}

For dynamic server urls please use uploadAsset:toURL:progress:completion method.

Delete task

Declarations:

- (void)deleteAssetWithIdentifier:(NSString *)identifier completion:(CRVCompletionBlock)completion;
- (void)deleteAssetFromURL:(NSURL *)url completion:(CRVCompletionBlock)completion;

Calling delete:

[[CRVNetworkManager sharedManager] deleteAssetWithIdentifier:identifier completion:^(BOOL success, NSError *error) {
	if (error) {
    	NSLog(@"Error: %@", error);
    } else {
    	NSLog(@"Success");
	}
}

For dynamic server urls please use uploadAsset:toURL:progress:completion method.

Asset types

As mentioned before, all uploaded objects should conform to CRVAssetType protocol. carrierwave-ios comes with ready to use classes for common image and video file types.

CRVImageAsset dellivers basic interface for creating image asset from NSURL to local image file or instance of NSData or UIImage. It supports gif, jpeg, tiff and png file types. After creation, image property gives you access to UI representation. You can make compressed copy of image with usage:

- (instancetype)compressedImageAssetWithQuality:(CGFloat)quality;

CRVVideoAsset provides handy methods to create asset object from NSData instance or from local video file. It supports mov and mp4 files. In addition, CRVVideoAsset can load selected video into AVPlayerItem with method:

- (void)loadVideoWithCompletion:(CRVVideoLoadCompletionBlock)completion; 

Usage example:

[asset loadVideoWithCompletion:^(AVPlayerItem *videoItem, NSError *error) {
	if (error) {
    	NSLog(@"Error: %@", error);
    } else {
    	NSLog(@"Video loaded");
	}
}];

Proccess management

CRVNetworkManager provides additional methods for handling lifecycle of upload or download processes, which are pretty straightforward and self-explanatory. As parameter all functions takes identifier returned by process creating methods.

- (void)cancelProccessWithIdentifier:(NSString *)identifier;
- (void)pauseProccessWithIdentifier:(NSString *)identifier;
- (void)resumeProccessWithIdentifier:(NSString *)identifier;

UI Component

UI component for editing selected photos, is responsible for scaling, rotating and croping them. [NGRCrop] (https://github.com/netguru/ngrcrop-ios.git)

Demo

carrierwave-ios comes with simple demo app which implements basic features of library like upload files and editing image assets. To run demo please follow the instructions below:

$ git clone --recursive [email protected]:netguru/carrierwave-ios.git
$ carthage update
$ pod install

or if you already cloned the project without --recursive:

$ git submodule update --init --recursive
$ carthage update
$ pod install

License

carrierwave-ios is available under the MIT license.

Contribution

First, thank you for contributing!

Here's a few guidelines to follow:

• we follow Ray Wenderlich Style Guide.
• write tests
• make sure the entire test suite passes

More Info

Have a question? Please open an issue!

Authors

Adrian Kashivskyy

• https://github.com/akashivskyy
• https://twitter.com/akashivskyy

Patryk Kaczmarek

• https://github.com/PatrykKaczmarek

Wojciech Trzasko

• https://github.com/WojciechTrzasko

Grzegorz Lesiak

• https://github.com/glesiak

Paweł Białecki

• https://github.com/ecler

Copyright © 2014-2015 Netguru