Read about some great apps made by fellow readers!

This is a post by Reader’s Apps Reviewer Ryan Poolos, an iOS Developer and founder of Frozen Fire Studios. Checkout his latest game, Cyborg Livestock. Checkout his latest website, iHelp.

Its that time again! May came fast and we’ve got a ton of apps to show for it. You’ve all been very busy building some very fun games and useful apps.

This month there are a lot of super addicting games, making it very hard to actually write the reviews instead of playing. Sorry Ray! :]

You guys blew away Aprils record for submissions. Over 45 incredible apps came through my inbox this month. Thank you all for your submissions.

As you know by now there’s only room to post fifteen reviews per month. Remember its not a popularity contest or judging, this is just something we do to help out our readers and build community. As such, active readers, forum members, and those who submit all the required information gain priority. The apps are not posted in any particular order or rank. Make sure you check out the Honorable mentions to try out the apps I didn’t have room for!

So get ready to find out about some awesomely fun apps and games by fellow readers!

Bricks Trouble Origins

Bricks Trouble Origins is ultra addicting. You’re a space pilot named Jed, and you like to blow up groups of blocks floating in space.

Where’d the blocks come from you ask? Don’t ask questions private!

The trick is you have to convert uneven clusters of bricks into perfect rectangles so they explode, adding some fun strategy to the game.

Features Game Center and OpenFeint so you can compete with your friends for high scores as well!

• Author: Pawel Pieciak @2PGames
• Most useful tutorial: Introduction to In-App Purchases
• App Store Link: Check it out!

Particulate

Particulate is a a fun tool for creating beautiful particle systems on your iPhone.

It’s very fun to play around with but it’s also very powerful. It even has the ability to layer multiple particles from a single emitter!

Performance in my experiments was very impressive as I pushed my aging iPhone 4 to the limits with 6 or 7 layers at a time all with radically different settings ranging from lifespan to color to spin.

It has everything you’d expect from a particle emitter. You can email yourself a plist for your newly created particle or use iTunes file sharing to download it to your computer. I didn’t try it but I’m sure using your created particle in CAParticleEmitter or Cocos2d would be a breeze. So get out there and start making particle systems on the go!

• Author: Tertius Steyn
• Most useful tutorial: UIKit Particle Systems in iOS 5
• App Store Link: Check it out!

Blow Out Monsters

Blow Out Monsters is a great action/strategy game. You control a space ship with a powerful laser cutting through space. Your goal is to divide and conquer all the monsters, by cutting pieces of the board out so the monsters are trapped outside.

The twist is you can turn on and off your laser but when you turn it on you lose your shield and are vulnerable to the monsters attacks. This makes for a really fun game that requires good timing, and better strategy!

• Author: Ibrahim ALIZ @ibrahimaliz
• Most useful tutorial: Rotating Turrets: How To Make A Simple iPhone Game with Cocos2D Part 2
• App Store Link: Check it out!

Color Pad for iPad

Color Pad is a freestyle drawing application with a clean and fun interface that gives you everything you need to make art.

How great that art is will depend on you :]

You can pull in pictures from your iPad’s photo library to give your picture a realistic background. Once you finish you can save it off to your iPad Photo Library or share it with friends through email and Facebook.

Color Pad for iPad is one of the simplest drawing apps I’ve seen. It gets all the interface distractions out of the way so you can just draw. Great for kids or overzealous adults who like to touch every button :)

Good news: Abdul threw in an extra promo for you guys! Grab it quick: YP3P6M4KRPEL. If you snag the code, please draw Abdul a thank you and post it to the comments :) Happy Coloring!

• Author: Abdul Azeem Khan @Abdul_azeem
• Most useful tutorial: How To Create a Simple iPhone App on iOS 5 Tutorial: 1/3
• App Store Link: Check it out!

Gravity Pop

Gravity Pop is an ultra addicting puzzle game where you control gravity itself!

Simple swipes on the screen change the gravity of the game board. Use your new found power over gravity to tip the scales in your favor as you try to pop groups of colored bubbles.

With three exciting game types, three bonus power ups, and global high scores you won’t be bored anytime soon.

Beware, power over gravity is addicting and will ruin other games for you as you try to cheat with simple swipes in other games. I tried to swipe the gravity in Angry Birds but it didn’t work :[ +1 Gravity Pop! Angry Birds 0.

Good news: Jonathan was kind enough to throw in some promos for you guys too! M7MXY9A9NHN4,734K3JYE6EN3,3PNRH46RHFFR,WY4N9R9KNKE3

• Author: Jonathan Sibley @jonsibley
• Most useful tutorial: Beginning Turn-Based Gaming with iOS 5
• App Store Link: Check it out!

Video+

Video+ is a great app for recording video with effects. Some really really cool effects. Its like Camera+ for Video. Imagine that haha!

I didn't count the effects but I'd bet theres over 30. And each effect has a full range of settings to adjust it. Some can be edited so far it's almost a completely different effect.

After you've recorded your video it's saved to your Camera Roll so you can do whatever you like with it. Including AirPlay out to your Apple TV. Definitely worth checking this one out.

• Author: Dawid Patek
• Most useful tutorial: OpenGL ES 2.0 for iPhone Tutorial
• App Store Link: Check it out!

Missing Melody

Do you more the death of CD's? Vinyls even? Do you love and miss the good old days of 8bit soundtracks? Then this game is for you!

In this game, your goal is to save the dying record industry. To do this, you transform into one of three characters and embark on a quest to retrieve all the lost CDs and records. But watch out for brick walls, snowcats, and giant pits in the ground!

Missing Melody has some awesome music. And a very cool controller system allowing you to pick between good old buttons, hidden touch zones, or simple swipe based controls.

Don't let the record music industry down!

• Author: Apikrit Panichevaluk @myice92ios
• Most useful tutorial: How To Make A Simple iPhone Game with Cocos2D Tutorial
  
• App Store Link: Check it out!

Gemstone Challenge

Gemstone challenge is a super addicting puzzle game based on matching gem blocks by color and shape. It has single player classic, timed modes, and online multiplayer through GameCenter.

If you're like me, then it won't take long to find the gems closing in on you. Thats where the multicolor super bombs come in to save the day and blast away entire rows at a time!

Brag about your high scores in the comments all you want (but don't expect to beat my 98,300)!

Good news: Julien was nice enough to give me an extra copy to pass along to you guys. Grab it quick! YLW76JNFEN44

• Author: Julien Wyart
• Most useful tutorial: How To Make A Simple Multiplayer Game with Game Center
• App Store Link: Check it out!

Flip the Bird

Flip the bird is a very special bird. His hunger knows no bounds. So much so that he devoured his own siblings!

Understandably, that made his parents kinda mad so the kicked him out of the nest. Your goal is to help him survive in the scary world outside, by dodging deadly bees and rocks.

Try to hitch a ride on a runaway crow or high strung squirrel. Use unsuspecting birds and mushrooms as boosts while you bounce and flap along.

You've never met a bird quite like Flip!

• Author: Hunter Mayer @FlipTheBirdGame
• Most useful tutorial: How to Create and Optimize Sprite Sheets in Cocos2d with Texture Packer and Pixel Formats
• App Store Link: Check it out!

Quadrobounce

Quadrobounce is single player pong on steroids, where you control four separate paddles using your iPhones accelerometer.

Did I mention there were four paddles? How about that they move around simultaneously exactly based on your tilt? Ok cool. ;]

This game is super simple to pick up and play but it definitely takes practice to master. GameCenter integration brings it all together. Quadrobounce!

• Author: Jonathan Hirz @jonnysuave
• Most useful tutorial: How To Make A Simple iPhone Game with Cocos2D
• App Store Link: Check it out!

RPS Mutants

RPS Mutants is fresh take on a good old favorite. Its rock, paper, scissors like you’ve never seen it before. In fact, its the cutest, most addicting rock, paper, scissors variation I’ve ever seen!

Rocks, pieces of paper, and you guessed it, pairs of scissors rain from the sky for some strange reason. You’re randomly assigned an item and you’ve got to stay clear of enemies that can hurt you and copies while trying to snag as many victories against the weak enemies as you can.

But beware or dangerous, shape-shifting, lightning that will mutate you into another RPS artifact and throw you off your game. Keep an eye out for powerups too like invincible shields and turboboosts.

• Author: Ken Toh @ken_toh
• Most useful tutorial: How to make a simple iPhone game with Cocos2d
• App Store Link: Check it out!

Pool Chalkboard

Pool Chalkboard will help you take your Pool to the next level.

You can use it to plan out your next shot with painstaking precision. Or you can show off that really cool trick shot you did down at the pub. Or if you’re like me and can’t play pool to save your life, you can show everyone what you were actually aiming for. :p

However you use it, Pool Chalkboard will make a great addition to any complex pool master conversation.

• Author: Robert Orich
• Most useful tutorial: How to submit your app to Apple from no account to App Store Part 1
• App Store Link: Check it out!

WordJams

Word Jams is a fresh take on word games.

After picking your difficulty (Hard Crust if you’re a man!) you’re given a fresh batch of toast to jam. One at a time you are given letters to place on your toast board. The goal is to try and lay them out to create as many words as possible.

After you’ve laid all your jam it will score your toast and determine how many words you made. Swiping will show you words made and tapping the words will show you their definition. Definitely original, definitely fun!

• Author: Patrick Smith
• Most useful tutorial: How to Save Your App Data with NSCoding and NSFileManager
• App Store Link: Check it out!

Picross HD

Picross is a fun puzzle game that give you numerical clues to help solve a pixel grid design.

It’s a very addicting game, with tons of puzzles to keep you going. If you manage to run out, there are several puzzle packs to buy in the app – including an Unlimited Daily puzzle upgrade for you hardcore Picrossers!

Good news: Tod was nice enough to give me some extra promo codes for you guys! Get them while they’re hot! Y3PRN9FRYW3T, JWNF39Y6W7AP, NXW737MWJ336

• Author: Tod Cunningham @fivelakesstudio
• Most useful tutorial: How To Localize an iPhone App Tutorial
• App Store Link: Check it out!

Zip Zap

Zip Zap is a killer 3D space game. Asteroids are all over the place crashing into your ship. Its up to you to blow them up with your power shield.

Tap where you want to go and blow up all the asteroids along your path. As you beat back the asteroids more will come. If you’re really good you’ll get more ground to cover. Powerups will help you along the way. Its super addicting once you get started.

Defend your ship at all costs! Oh, by the way, I made it to 338,807! Beat that!

• Author: Rani Lian
• Most useful tutorial: How to Integrate iAd into your iPhone App
• App Store Link: Check it out!

Honorable Mentions

Here are the apps that didn’t get reviewed. Remember it wasn’t a popularity contest or even a rating contest. Forum members got priority among other factors. Your apps were great and I’m sorry we didn’t have time to review them all!

Feed Browser

Worktime Radar

Awesome Cowbell

Monster Mayhem Apocalypse

Picky Fruit

iBehave

Dream Guy

Period Plus

Linsanity Rush

iSalePrice

Reddit Photo Clock

Qi iQ – Learn Two letter Words

Baby Shaper

BallsBreaker

Dilemmas

My Kids Health

Where2Boss

World of Luck

Where To Go From Here?

Thats it for May! Looking forward to the apps you make next month! Since we’re getting so many responses to better your odds, please make sure you include all the requested information the first time around.

If you are a reader of this site and would like to be considered for this column, shoot an email to ryan@raywenderlich.com with the following info:

• Your full name and Twitter account if you have one
• The name of your app
• A promo code for your app (Even if its free)
• A link directly to your app in itunes.
• The tutorial on the site that was most helpful to development of your app
• Your forum account name if you have one (priority given to active forum members)

I hope you enjoyed this column, and I look forward to seeing what you guys come up with this month! :]

This is a post by Reader’s Apps Reviewer Ryan Poolos, an iOS Developer and founder of Frozen Fire Studios. Checkout his latest game, Cyborg Livestock. Checkout his latest website, iHelp.

Readers App Reviews – May 2012 is a post from: Ray Wenderlich

Learn how to make a complete UIDocument + iCloud app!

This is a blog post by site administrator Ray Wenderlich, an independent software developer and gamer.

Welcome back to the final part of our document-based iCloud app tutorial series!

In this tutorial series we are making a complete document-based iCloud app called PhotoKeeper, with features that go beyond just the basics.

In the first and second part of the series, we made a fully functional UIDocument-based app that works with local files with full CRUD support.

In this third part of the series, we got iCloud mostly working. All CRUD operations are functional, and you can even rename and delete files.

That brings us to this fourth and final part of the series! Here we’ll show you how you can resolve conflicts, and move/copy files to/from iCloud.

This project continues where we left off last time, so if you don’t have it already grab the previous code sample and open up the project. Let’s wrap this project up!

iCloud and Conflicts: Overview

Open your project and open the same document on two different devices. Change the picture on both at the same time, tap Done, and see what happens.

Basically iCloud will automatically choose the “lastest change” as the current document by default. But since this is dependent on network connections, this might not be what the user actually wants.

The good news is when the same document is modified at the same time like this, iCloud will detect this as a conflict and store copies of any conflicting documents. It’s up to you how you deal with the conflict – you could try to merge changes or let the user pick one (or more) of the versions to keep.

In this tutorial, when there’s a conflict we’re going to display a view controller to the user that shows the conflicts and allows the user to pick one of them to keep. You might want to use a slightly different strategy for your app, but the same core idea remains.

Displaying Conflicts

The first thing we need to do is display and detect conflicts. UIDocument has a property called documentState that is a bitfield of different flags that can be on a document, including a “conflict” state.

We’ve actually been passing this along in our PTKEntry all along, now’s our chance to actually use it!

Let’s start by just logging out what the document state is when we read documents. Make the following changes to PTKMasterViewController.m:

// Add to top of "Helpers" section
- (NSString *)stringForState:(UIDocumentState)state {
    NSMutableArray * states = [NSMutableArray array];
    if (state == 0) {
        [states addObject:@"Normal"];
    }
    if (state & UIDocumentStateClosed) {
        [states addObject:@"Closed"];
    }
    if (state & UIDocumentStateInConflict) {
        [states addObject:@"In Conflict"];
    }
    if (state & UIDocumentStateSavingError) {
        [states addObject:@"Saving error"];
    }
    if (state & UIDocumentStateEditingDisabled) {
        [states addObject:@"Editing disabled"];
    }
    return [states componentsJoinedByString:@", "];
}
 
// Replace "Loaded File URL" log line in loadDocURL with the following
NSLog(@"Loaded File URL: %@, State: %@, Last Modified: %@", [doc.fileURL lastPathComponent], [self stringForState:state], version.modificationDate.mediumString);

Compile and run your app, and if you have any documents in the conflict state you should see something like this:

Loaded File URL: Photo 4.ptk, State: In Conflict, Last Modified: Today 10:01:17 AM

Let’s modify our app to have a visual representation of when a document is in the conflict state. Open MainStoryboard.storyboard and add a 32×32 image view to the bottom left of the thumbnail image view, and set the image to warning.png:

Then switch to PTKEntryCell.h and add a property for this:

@property (weak, nonatomic) IBOutlet UIImageView * warningImageView;

And synthesize it in PTKEntryCell.m:

@synthesize warningImageView;

Switch back to MainStoryboard.storyboard, control-drag from the cell to the warning image view, and connect it to the warningImageView outlet.

Finally, open PTKMasterViewController.m and add this to the end of tableView:cellForRowAtIndexPath (before the call to return cell):

if (entry.state & UIDocumentStateInConflict) {
    cell.warningImageView.hidden = NO;
} else {
    cell.warningImageView.hidden = YES;
}

Compile and run, and now if there is a conflict you should see a warning flag next to the document in question!

Creating a Conflict View Controller

Now that we know what documents are in conflict, we have to do something about it. We’ll create a view controller that lists all the versions that are available and let the user choose one to keep.

Create a new file with the iOS\Cocoa Touch\Objective-C class template, name it PTKConflictViewController, and make it a subclass of UITableViewController. Make sure the checkboxes are NOT checked, and finish creating the file.

We’ll add the code for this later, first let’s design the UI. Open MainStoryboard.storyboard, and drag a new UITableViewController into the storyboard below the detail view controller.

We want the master view controller to display it, so control-drag from the master view controller to the new table view controller, and choose Push from the popup. Then click the segue and name it “showConflicts”:

Next zoom in to 100% size and let’s set up the table view cell. Set the row height to 80, and add an image view and two labels roughly like the following:

We could create a custom cell sublass like we did before for the master table view, but I’m feeling lazy so we’ll look up the subviews by tag instead. So set the tag of the image view to 1, the first label to 2, and the second label to 3.

To finish configuring the cell we need to set a cell reuse identifier for our cell so we can dequeue it. Select the Table View Cell and set the Identifeir to MyCell.

Finally, we need to set the class of our view controller. Select the table View Controller and in the identity inspector set the cass to PTKConflictViewController.

Before we implement the PTKConflictViewController, we should create a class to keep track of everything we need to know for each cell (similar to PTKEntry).

For a conflicted file, you can get a list of all of the different versions of the file that are in conflict. These versions are referenced via the NSFileVersion class.

So we need to keep track of the NSFileVersion for each row, open that version and get its metadata as well (so we can display the thumbnail to the user).

Create a new file with the iOS\Cocoa Touch\Objective-C class template, name it PTKConflictEntry, and make it a subclass of NSObject. Then replace the contents of PTKConflictEntry.h with the following:

#import <Foundation/Foundation.h>
 
@class PTKMetadata;
 
@interface PTKConflictEntry : NSObject
 
@property (strong) NSFileVersion * version;
@property (strong) PTKMetadata * metadata;
 
- (id)initWithFileVersion:(NSFileVersion *)version metadata:(PTKMetadata *)metadata;
 
@end

And replace PTKConflictEntry.m with the following:

#import "PTKConflictEntry.h"
 
@implementation PTKConflictEntry
@synthesize version = _version;
@synthesize metadata = _metadata;
 
- (id)initWithFileVersion:(NSFileVersion *)version metadata:(PTKMetadata *)metadata {
    if ((self = [super init])) {
        self.version = version;
        self.metadata = metadata;
    }
    return self;
}
 
@end

Finally onwards to implementing PTKConflictViewController! When displaying the view controller, we’ll pass in the fileURL to display conflicts for, so modify PTKConflictViewController.h to the following:

#import <UIKit/UIKit.h>
 
@interface PTKConflictViewController : UITableViewController
 
@property (strong) NSURL * fileURL;
 
@end

Then make the following changes to PTKConflictViewController.m:

// Add imports to the top of the file
#import "PTKConflictEntry.h"
#import "PTKDocument.h"
#import "PTKMetadata.h"
#import "NSDate+FormattedStrings.h"
 
// Modify @implementation to add a private instance variable for the entries and synthesize fileURL
@implementation PTKConflictViewController {
    NSMutableArray * _entries;
}
@synthesize fileURL;
 
// Add to end of viewDidLoad
_entries = [NSMutableArray array];
 
// Replace numberOfSectionsInTableView, numberOfRowsInSection, and cellForRowAtIndexPath with the following
- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView
{
    return 1;
}
 
- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section
{
    NSLog(@"%d rows", _entries.count);
    return _entries.count;
}
 
- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
    static NSString *CellIdentifier = @"MyCell";
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:CellIdentifier];
 
    // Configure the cell...
    UIImageView * imageView = (UIImageView *) [cell viewWithTag:1];
    UILabel * titleLabel = (UILabel *) [cell viewWithTag:2];
    UILabel * subtitleLabel = (UILabel *) [cell viewWithTag:3];
    PTKConflictEntry * entry = [_entries objectAtIndex:indexPath.row];
 
    if (entry.metadata) {
        imageView.image = entry.metadata.thumbnail;
    }
    titleLabel.text = [NSString stringWithFormat:@"Modified on %@", entry.version.localizedNameOfSavingComputer];
    subtitleLabel.text = [entry.version.modificationDate mediumString];
 
    return cell;
}

OK so that’s pretty straightforward – we’re just displaying any PTKConflictEntry classes in the _entries array.

But what about creating these PTKConflictEntry classes in the first place from the fileURL? We’ll do that in viewWillAppear. Add this right after viewDidUnload:

- (void)viewWillAppear:(BOOL)animated {
 
    [_entries removeAllObjects];    
    NSMutableArray * fileVersions = [NSMutableArray array];
 
    NSFileVersion * currentVersion = [NSFileVersion currentVersionOfItemAtURL:self.fileURL];
    [fileVersions addObject:currentVersion];
 
    NSArray * otherVersions = [NSFileVersion otherVersionsOfItemAtURL:self.fileURL];
    [fileVersions addObjectsFromArray:otherVersions];
 
    for (NSFileVersion * fileVersion in fileVersions) {
 
        // Create a resolve entry and add to entries
        PTKConflictEntry * entry = [[PTKConflictEntry alloc] initWithFileVersion:fileVersion metadata:nil];
        [_entries addObject:entry];
        NSIndexPath * indexPath = [NSIndexPath indexPathForRow:_entries.count-1 inSection:0];
 
        // Open doc and get metadata - when done, reload row so we can get thumbnail
        PTKDocument * doc = [[PTKDocument alloc] initWithFileURL:fileVersion.URL];
        NSLog(@"Opening URL: %@", fileVersion.URL);
        [doc openWithCompletionHandler:^(BOOL success) {
            if (success) {
                dispatch_async(dispatch_get_main_queue(), ^{
                    entry.metadata = doc.metadata;
                    [self.tableView reloadRowsAtIndexPaths:[NSArray arrayWithObject:indexPath] withRowAnimation:UITableViewRowAnimationNone];
                });
                [doc closeWithCompletionHandler:nil];
            }
        }];
    }
 
    [self.tableView reloadData];
}

To get the different versions of the file that are in conflict, you use two different APIs in NSFileVersion – currentVersionOfItemAtURL (the current “winning” version), and otherVersionsOFItemAtURL (the other ones that iCloud isn’t sure about). We open up all of these versions and add them to our array, along with their metadata (thumbnail).

Finally, when the user taps a row we want to choose that file version and resolve the conflict. So replace didSelectRowAtIndexPath at the end of the file with this:

- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath {
 
    PTKConflictEntry * entry = [_entries objectAtIndex:indexPath.row];
 
    if (![entry.version isEqual:[NSFileVersion currentVersionOfItemAtURL:self.fileURL]]) {
        [entry.version replaceItemAtURL:self.fileURL options:0 error:nil];    
    }
    [NSFileVersion removeOtherVersionsOfItemAtURL:self.fileURL error:nil];
    NSArray* conflictVersions = [NSFileVersion unresolvedConflictVersionsOfItemAtURL:self.fileURL];
    for (NSFileVersion* fileVersion in conflictVersions) {
        fileVersion.resolved = YES;
    }
 
    [self.navigationController popViewControllerAnimated:YES];    
 
}

If the user chose one of the “other” versions of the file, we replace the current version of the file with what they chose.

We then remove all the other versions, and mark everything as resolved. Not too hard, eh?

Almost ready to try this out! Just make the following changes to PTKMasterViewController.m:

// Add new private variable
NSURL * _selURL;
 
// Modify didSelectRowAtIndexPath to check documenet state first
- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath {
 
    PTKEntry * entry = [_objects objectAtIndex:indexPath.row];
    [self.tableView deselectRowAtIndexPath:indexPath animated:YES];
 
    if (entry.state & UIDocumentStateInConflict) {
 
        _selURL = entry.fileURL;
        [self performSegueWithIdentifier:@"showConflicts" sender:self];
 
    } else {
 
        _selDocument = [[PTKDocument alloc] initWithFileURL:entry.fileURL];    
        [_selDocument openWithCompletionHandler:^(BOOL success) {
            NSLog(@"Selected doc with state: %@", [self stringForState:_selDocument.documentState]);
 
            dispatch_async(dispatch_get_main_queue(), ^{
                [self performSegueWithIdentifier:@"showDetail" sender:self];
            });
        }];
 
    }
} 
 
// Modify prepareForSegue to add a case for the showConflicts segue
- (void)prepareForSegue:(UIStoryboardSegue *)segue sender:(id)sender
{
    if ([[segue identifier] isEqualToString:@"showDetail"]) {
        [[segue destinationViewController] setDelegate:self];
        [[segue destinationViewController] setDoc:_selDocument];
    } else if ([[segue identifier] isEqualToString:@"showConflicts"]) {
        [[segue destinationViewController] setFileURL:_selURL];
    }
}

And that’s it! Compile and run, and now when you tap an entry with a conflict you will now see the list of versions in conflict:

And you can tap a file to restore to that verison and resolve the conflict:

Moving Files To iCloud

At this point our app is almost done, except for one more bit – dealing with the user transitioning between iCloud off and iCloud on, and vice versa. There are two cases:

• local => iCloud. If the user isn’t using iCloud (and has local files) and starts using iCloud, the app should automatically move all the local files to iCloud (renaming files if necesary to avoid name conflicts).
• iCloud => local. If the user is using iCloud and wants to turn iCloud off and use local files, we should ask the user what he wants to do. The options are “copy the iCloud files to local”, “keep files on iCloud”, or “switch back to using iCloud.”

Let’s start with the first case. We already have the stub for localToiCloud called in the proper situation (we covered this in part 3). So make the following changes to PTKMasterViewController.m:

// Add a new private instance variable
BOOL _moveLocalToiCloud;
 
// Replace localToiCloud with the following (and add a new method)
- (void)localToiCloudImpl {
    // TODO
}
 
- (void)localToiCloud {
    NSLog(@"local => iCloud");
 
    // If we have a valid list of iCloud files, proceed
    if (_iCloudURLsReady) {
        [self localToiCloudImpl];
    } 
    // Have to wait for list of iCloud files to refresh
    else {
        _moveLocalToiCloud = YES;         
    }
}
 
// Add to end of processiCloudFiles, right before enableUpdates
if (_moveLocalToiCloud) {            
    _moveLocalToiCloud = NO;
    [self localToiCloudImpl];            
}

OK, what’s going on here? Well, to move the files to iCloud we need to make sure there are no name conflicts. But we can’t know what files are in iCloud until the list of files returns from our NSMetadataQuery. So if the list of iCloud URLs isn’t ready, we set a flag to YES. When the metadata query results come in, we check this flag and call localToiCloudImpl (which will do the actual work) now that we have a valid list of filenames.

Next we need to make a slight tweak to getDocFilename so it can search in the list of iCloudURLs (instead of the list of PTKEntries). Make the following changes:

// Add right above getDocFilename:uniqueInObjects
- (BOOL)docNameExistsIniCloudURLs:(NSString *)docName {
    BOOL nameExists = NO;
    for (NSURL * fileURL in _iCloudURLs) {
        if ([[fileURL lastPathComponent] isEqualToString:docName]) {
            nameExists = YES;
            break;
        }
    }
    return nameExists;
}
 
// Replace TODO in docFilename:uniqueInObjects with this
nameExists = [self docNameExistsIniCloudURLs:newDocName];

So by passing in NO to docNameExists:uniqueInObjects we can have it make sure the name is unique in the iCloud URLs (even if iCloud if off).

Next replace localToiCloudImpl with the following:

- (void)localToiCloudImpl {
 
    NSLog(@"local => iCloud impl");
 
    NSArray * localDocuments = [[NSFileManager defaultManager] contentsOfDirectoryAtURL:self.localRoot includingPropertiesForKeys:nil options:0 error:nil];
    for (int i=0; i < localDocuments.count; i++) {
 
        NSURL * fileURL = [localDocuments objectAtIndex:i];
        if ([[fileURL pathExtension] isEqualToString:PTK_EXTENSION]) {
 
            NSString * fileName = [[fileURL lastPathComponent] stringByDeletingPathExtension];
            NSURL *destURL = [self getDocURL:[self getDocFilename:fileName uniqueInObjects:NO]];
 
            // Perform actual move in background thread
            dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^(void) {
                NSError * error;
                BOOL success = [[NSFileManager defaultManager] setUbiquitous:self.iCloudOn itemAtURL:fileURL destinationURL:destURL error:&error];
                if (success) {
                    NSLog(@"Moved %@ to %@", fileURL, destURL);
                    [self loadDocAtURL:destURL];
                } else {
                    NSLog(@"Failed to move %@ to %@: %@", fileURL, destURL, error.localizedDescription); 
                }
            });
 
        }
    }
 
}

This is the meat of the move logic. We loop through all of our local files, and get a unique filename for the local filename in iCloud. We then move the document to iCloud, which you can do by calling the setUbiquitous:itemAtURL:destinationItem method.

Compile and run the app, and make sure iCloud is off. Create a local document, and turn iCloud back on. Your local document should move to iCloud!

Copying Files From iCloud

Now let’s try the other way around. Make the following changes to PTKMasterViewController.m:

// Add new instance variable
BOOL _copyiCloudToLocal;
 
// Replace iCloudToLocal and add a stub
- (void)iCloudToLocalImpl {
 
    NSLog(@"iCloud => local impl");
    // TODO
}
 
- (void)iCloudToLocal {
    NSLog(@"iCloud => local");
 
    // Wait to find out what user wants first
    UIAlertView * alertView = [[UIAlertView alloc] initWithTitle:@"You're Not Using iCloud" message:@"What would you like to do with the documents currently on this iPad?" delegate:self cancelButtonTitle:@"Continue Using iCloud" otherButtonTitles:@"Keep a Local Copy", @"Keep on iCloud Only", nil];
    alertView.tag = 2;
    [alertView show];
 
}
 
// Add second case in alertView:didDismissWithButtonIndex
// @"What would you like to do with the documents currently on this iPad?" 
// Cancel: @"Continue Using iCloud" 
// Other 1: @"Keep a Local Copy"
// Other 2: @"Keep on iCloud Only"
else if (alertView.tag == 2) {
 
    if (buttonIndex == alertView.cancelButtonIndex) {
 
        [self setiCloudOn:YES];
        [self refresh];
 
    } else if (buttonIndex == alertView.firstOtherButtonIndex) {
 
        if (_iCloudURLsReady) {
            [self iCloudToLocalImpl];
        } else {
            _copyiCloudToLocal = YES;
        }
 
    } else if (buttonIndex == alertView.firstOtherButtonIndex + 1) {            
 
        // Do nothing
 
    } 
 
}
 
// Add to end of processiCloudFiles, right before call to enableUpdates
else if (_copyiCloudToLocal) {
    _copyiCloudToLocal = NO;
    [self iCloudToLocalImpl];
}

This follows a similar strategy to what we did before, except we give the user a chance to choose what to do first.

Next replace iCloudToLocalImpl with the following:

- (void)iCloudToLocalImpl {
 
    NSLog(@"iCloud => local impl");
 
    for (NSURL * fileURL in _iCloudURLs) {
 
        NSString * fileName = [[fileURL lastPathComponent] stringByDeletingPathExtension];
        NSURL *destURL = [self getDocURL:[self getDocFilename:fileName uniqueInObjects:YES]];
 
        // Perform copy on background thread
        dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^(void) {            
            NSFileCoordinator* fileCoordinator = [[NSFileCoordinator alloc] initWithFilePresenter:nil];
            [fileCoordinator coordinateReadingItemAtURL:fileURL options:NSFileCoordinatorReadingWithoutChanges error:nil byAccessor:^(NSURL *newURL) {
                NSFileManager * fileManager = [[NSFileManager alloc] init];
                NSError * error;
                BOOL success = [fileManager copyItemAtURL:fileURL toURL:destURL error:&error];                     
                if (success) {
                    NSLog(@"Copied %@ to %@ (%d)", fileURL, destURL, self.iCloudOn);
                    [self loadDocAtURL:destURL];
                } else {
                    NSLog(@"Failed to copy %@ to %@: %@", fileURL, destURL, error.localizedDescription); 
                }
            }];
        });
    }
 
}

Here we use NSFileManager’s copyItemAtURL to copy the file, making sure to wrap it in an NSFileCoordinator for safety.

Compile and run the app, and make sure iCloud is enabled. Then switch to Settings and disable iCloud, and this will appear:

If you tap “Keep a Local Copy”, you will see the items all copied locally for you! :]

Where To Go From Here?

Here is a download with the state of the code sample so far.

Congratulations, you have made a semi-real world document-based iCloud app! It can do all the basic CRUD operations, as well as the more tricky bits like handling conflicts, handling both local and iCloud documents, and having the capability to switch documents between the two.

I don’t claim to have done everything in the best possible manner in this tutorial or made no mistakes. As such, I have put this project on GitHub in case anyone wants to take it from here and add any fixes/improvements moving forward.

I hope this tutorial has been useful to anyone trying to get iCloud working with a document-based app. If you have any questions, comments, or suggestions for improvement, please join the forum discussion below! :]

This is a blog post by site administrator Ray Wenderlich, an independent software developer and gamer.

iCloud and UIDocument: Beyond the Basics. Part 4/4 is a post from: Ray Wenderlich

Learn how to make a complete UIDocument + iCloud app!

This is a blog post by site administrator Ray Wenderlich, an independent software developer and gamer.

Welcome back to our document-based iCloud app tutorial series!

In this tutorial series we are making a complete document-based iCloud app called PhotoKeeper, with features that go beyond just the basics.

In the first and second part of the series, we made a fully functional UIDocument-based app that works with local files with full CRUD support.

In this third part of the series, it’s finally time to dive into iCloud! We will get almost everything working on iCloud in this tutorial, except for some subtle bits which we’ll leave for the final part of the series.

This project continues where we left off last time, so if you don’t have it already grab the previous code sample and open up the project. It’s iCloud time, baby!

Checking if iCloud is Available

Before you can use iCloud, you first need to check if it is available by calling NSFileManager’s URLForUbiquityContainerIdentifier method.

This method also initializes iCloud for you, and returns the URL of the “iCloud directory” – that is, the directory that that the iCloud daemon checks for files to sychronize to the cloud.

This call might block so it’s important to call it from a background thread. Let’s try it out. Open PTKMasterViewController.m and make the following changes:

// Add new private instance variable
NSURL * _iCloudRoot;
BOOL _iCloudAvailable;
 
// Add to end of "Helpers" section
- (void)initializeiCloudAccessWithCompletion:(void (^)(BOOL available)) completion {
    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
        _iCloudRoot = [[NSFileManager defaultManager] URLForUbiquityContainerIdentifier:nil];
        if (_iCloudRoot != nil) {
            dispatch_async(dispatch_get_main_queue(), ^{
                NSLog(@"iCloud available at: %@", _iCloudRoot);
                completion(TRUE);
            });            
        }            
        else {
            dispatch_async(dispatch_get_main_queue(), ^{
                NSLog(@"iCloud not available");
                completion(FALSE);
            });
        }
    });
}

The most important part here is that we call URLForUbiquityContainerIdentifier to figure out where the iCloud root directory is. If it returns nil, that means iCloud isn’t available.

Notice we take a block as a parameter – it’s a method we’ll call after URLForUbiquityContainerIdentifier completes to indicate whether or not iCloud is available. If you’re a bit rusty on blocks, you might want to check out our blocks tutorial.

Now let’s try this out. Go to the refresh method and replace it with the following:

- (void)refresh {
 
    [_objects removeAllObjects];
    [self.tableView reloadData];
 
    self.navigationItem.rightBarButtonItem.enabled = NO;
    [self initializeiCloudAccessWithCompletion:^(BOOL available) {
 
        _iCloudAvailable = available;
 
        // TODO
 
        if (![self iCloudOn]) {
            [self loadLocal];        
        }
 
    }];
}

The only difference here is we wait until we check if iCloud is available before refreshing our list of files.

Compile and run the app on your device – not the simulator, because iCloud doesn’t work on the simulator. You should see this in the console:

iCloud not available

You should see this whether you have iCloud enabled or not in Settings. What gives?

This is because for your app to use iCloud, you have to do several project configuration steps. Let’s get to it!

Configuring your Project for iCloud

The first step is to visit the iOS Developer Center and go to the iOS Provisioning Portal. Click App IDs in the sidebar and then New App ID. Create an App ID for your app, similar to the following:

After you are done, you will see your App ID in the list:

Note that iCloud is not enabled by default – you have to configure it. To do so, simply click the Configure button, check the checkbox for Enable for iCloud, and click Done.

Next you need to create a provisioning profile for your App ID. Click the Provisioning tab, click New Profile, and select the appropriate information like you can see below.

After you finish creating the profile, refresh the page until it is available for download, and download it. Double click it to install it in Xcode. You should see it in the Organizer when you’re done:

Next, you need to set up your Xcode project to use this provisioning profile. Click your project in the Project Navigator, select the PhotoKeeper target, adn go to the Build Settings tab. Search for code sign, and set the code signing identity to your new provisioning profile.

To use iCloud, you need to set up some Entitlements that gives your app access to the iCloud directory. This used to be a pain but now it’s extremely simple. Just go to the Summary tab and click the checkbox for Enable Entitlements. It should autofill everything else, but sometimes I’ve seen it not fill out the iCloud Containers section, so you might have to click the plus button and add it if so.

The last step is you need to configure your app to recognize the file types for the documents the app is storing. This isn’t absolutely required at this point, but you will run into troubles if you don’t do it later so you might as well do it now.

Switch to the Info tab and click the plus button in the bottom right. In the pop-up, select Add Document Type.

You will see that it has created a new entry for you in the Document Types list above. Fill it out similarly to this example:

Next click the plus button again but select Add Exported UTI this time.

It will create a new entry for you in the Exported UTIs list above. Fill it out similarly to this example:

It is important that whatever you put for Identifier here matches what you put for Types in the Document Types. Also, I have had trouble with filename extensions that weren’t exactly 3 characters in length, so if you have any troubles in your app try working with 3 character extensions.

Phew – finally done! Compile and run your app, and if all works well you should now see something like this in the console:

iCloud available at: file://localhost/private/var/mobile/Library/Mobile%20Documents/
KFCNEC27GU~com~razeware~PhotoKeeper/

This gives you the directory on the device where you can find and create iCloud files. The iCloud daemon will automatically pull down new files to this directory as they become available, update files that are there, watch for changes you put there, etc.

We’ll use this directory a lot in this tutorial, but before we go we have the first tricky bit about iCloud to discuss – turning iCloud on and off.

iCloud On, iCloud Off

Like we mentioned back in part 1, you shouldn’t just assume you should use iCloud if it’s available – you should allow the user to enable/disable iCloud for your app.

And also like we discussed before, I believe the best place for this configuration option is in Settings (rather than in-app settings). This way it reduces clutter in your app and discourages users from changing it unnecessarily.

Adding a switch to turn iCloud on and off is easy, so let’s deal with that first. Create a new file with the iOS\Resource\Settings Bundle template, and name it Settings.bundle. Open Settings.bundle\Root.plist, and modify the file to look like the following:

Compile and run the app on your device, and switch to the Settings app. Scroll down to find the category for PhotoKeeper, and you should see a switch for iCloud:

Settings is pretty cool because getting the value for this switch is as easy as reading the “iCloudOn” key from NSUserDefaults.

Now that we’ve got a switch, it starts getting tricky. We have to make sure we have code that handles all of the following cases:

• If iCloud isn’t switched on, but it’s available (and we haven’t bugged the user already), ask the user if they want to turn on iCloud. This way they don’t necessarily have to go to Settings at all.
• If iCloud isn’t available, but it was on before, warn the user that although the app can’t access their iCloud files anymore, they’re still out on the cloud.
• If iCloud was switched on (but wasn’t previously), that means we need to move our local files to iCloud.
• If iCloud was switched off (but wasn’t previously), that means we need to ask the user what to do with the old iCloud files. The user might want to leave them on iCloud, keep a copy, or change their mind and turn iCloud back on again.

To accomplish all this, in addition to the “iCloudOn” flag managed by Settings, we need to create two more NSUserDefaults flags – one for if iCloud “used to be on”, and one for if we’ve prompted the user if they want to use iCloud yet.

Add these wrappers to PTKMasterViewController.m at the top of the “Helpers” section (overwriting the old iCloudOn method):

- (BOOL)iCloudOn {    
    return [[NSUserDefaults standardUserDefaults] boolForKey:@"iCloudOn"];
}
 
- (void)setiCloudOn:(BOOL)on {    
    [[NSUserDefaults standardUserDefaults] setBool:on forKey:@"iCloudOn"];
    [[NSUserDefaults standardUserDefaults] synchronize];
}
 
- (BOOL)iCloudWasOn {    
    return [[NSUserDefaults standardUserDefaults] boolForKey:@"iCloudWasOn"];
}
 
- (void)setiCloudWasOn:(BOOL)on {    
    [[NSUserDefaults standardUserDefaults] setBool:on forKey:@"iCloudWasOn"];
    [[NSUserDefaults standardUserDefaults] synchronize];
}
 
- (BOOL)iCloudPrompted {
    return [[NSUserDefaults standardUserDefaults] boolForKey:@"iCloudPrompted"];
}
 
- (void)setiCloudPrompted:(BOOL)prompted {    
    [[NSUserDefaults standardUserDefaults] setBool:prompted forKey:@"iCloudPrompted"];
    [[NSUserDefaults standardUserDefaults] synchronize];
}

Then make the following changes to PTKMasterViewController.m:

// Add some stub methods to the bottom of the "File management" section
- (void)iCloudToLocal {
    NSLog(@"iCloud => local");
}
 
- (void)localToiCloud {
    NSLog(@"local => iCloud");
}
 
#pragma mark iCloud Query
 
- (void)startQuery {        
    NSLog(@"Starting to watch iCloud dir...");
}
 
// Replace the "TODO" in refresh with the following
if (!_iCloudAvailable) {
 
    // If iCloud isn't available, set promoted to no (so we can ask them next time it becomes available)
    [self setiCloudPrompted:NO];
 
    // If iCloud was toggled on previously, warn user that the docs will be loaded locally
    if ([self iCloudWasOn]) {
        UIAlertView * alertView = [[UIAlertView alloc] initWithTitle:@"You're Not Using iCloud" message:@"Your documents were removed from this iPad but remain stored in iCloud." delegate:nil cancelButtonTitle:nil otherButtonTitles:@"OK", nil];
        [alertView show];
    }
 
    // No matter what, iCloud isn't available so switch it to off.
    [self setiCloudOn:NO]; 
    [self setiCloudWasOn:NO];
 
} else {        
 
    // Ask user if want to turn on iCloud if it's available and we haven't asked already
    if (![self iCloudOn] && ![self iCloudPrompted]) {
 
        [self setiCloudPrompted:YES];
 
        UIAlertView * alertView = [[UIAlertView alloc] initWithTitle:@"iCloud is Available" message:@"Automatically store your documents in the cloud to keep them up-to-date across all your devices and the web." delegate:self cancelButtonTitle:@"Later" otherButtonTitles:@"Use iCloud", nil];
        alertView.tag = 1;
        [alertView show];
 
    } 
 
    // If iCloud newly switched off, move local docs to iCloud
    if ([self iCloudOn] && ![self iCloudWasOn]) {                    
        [self localToiCloud];                                                           
    }                
 
    // If iCloud newly switched on, move iCloud docs to local
    if (![self iCloudOn] && [self iCloudWasOn]) {
        [self iCloudToLocal];                    
    }
 
    // Start querying iCloud for files, whether on or off
    [self startQuery];
 
    // No matter what, refresh with current value of iCloudOn
    [self setiCloudWasOn:[self iCloudOn]];
 
}
 
// Add right after the refresh method
#pragma mark UIAlertViewDelegate
 
- (void)alertView:(UIAlertView *)alertView didDismissWithButtonIndex:(NSInteger)buttonIndex {
 
    // @"Automatically store your documents in the cloud to keep them up-to-date across all your devices and the web."
    // Cancel: @"Later"
    // Other: @"Use iCloud"
    if (alertView.tag == 1) {
        if (buttonIndex == alertView.firstOtherButtonIndex) 
        {
            [self setiCloudOn:YES];            
            [self refresh];
        }                
    } 
}

There’s a lot of code here, but none of it is very complicated – it’s just implementing the logic discussed earlier. Be sure to read through the refresh method to make sure you understand the basic logic there.

You may wonder why we’re calling “startQuery” even if iCloud is off. We’re going to need valid a list of iCloud files for when we implement the iCloudToLocal method. But don’t worry, we won’t display the list if iCloud is off. More on this later.

There’s one final step. Since the user can leave the app and change the value in Settings at any time, we need to refresh whenever the user returns to the app (i.e. the app “didbecomeactive”). So make the following changes to listen for that event:

// Add to the bottom of viewDidLoad
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(didBecomeActive:) name:UIApplicationDidBecomeActiveNotification object:nil];
 
// Add right after viewDidLoad
- (void)didBecomeActive:(NSNotification *)notification {    
    [self refresh];
}

Run the app and perform the following steps:

• Make sure iCloud is off and create a local file. Switch to settings and turn iCloud off. You should no longer see the file.
• Make sure iCloud is on and go to Settings\iCloud\Documents and Data and switch it off. This effectively makes iCloud not available. Switch back to the app and you should get a popup, and it should switch to iCloud off automatically.
• Switch back to Settings and make iCloud available again. Switch back to the app and it will tell you iCloud is available and ask if you want to turn it on.
• Play around with switching iCoud on and off, ana make sure the appropriate “local => iCloud” or “iCloud => local” messages print out.

Nice! Now that we have this firm framework in place, all we really need to care about from here on out is whether “iCloudOn” is YES or NO. If YES, we should be displaying iCloud files, otherwise local files.

But we haven’t covered yet how to get a list of iCloud files. Let’s cover that now!

Querying iCloud Files

As we mentioned in part 1, you can’t just enumerate the iCloud directory with NSFileManager APIs like you do for the documents directory. Instead, you have to use a fancy API called NSMetadataQuery.

This API lets you set up a search on a directory, such as “give me all files that end with PTK”. It will return the initial results, and then continue to watch the directory for you, sending you update notifications as they come in. It’s pretty handy and efficient in comparison to the alternative (periodic polling).

Let’s see what it looks like. Go to the “iCloud Query” section and add this right above startQuery:

- (NSMetadataQuery *)documentQuery {
 
    NSMetadataQuery * query = [[NSMetadataQuery alloc] init];
    if (query) {
 
        // Search documents subdir only
        [query setSearchScopes:[NSArray arrayWithObject:NSMetadataQueryUbiquitousDocumentsScope]];
 
        // Add a predicate for finding the documents
        NSString * filePattern = [NSString stringWithFormat:@"*.%@", PTK_EXTENSION];
        [query setPredicate:[NSPredicate predicateWithFormat:@"%K LIKE %@",
                             NSMetadataItemFSNameKey, filePattern]];        
 
    }
    return query;
 
}

When you create a NSMetadataQuery, you can tell it to watch the “Documents” subdirectory of the iCloud root (this is where we’ll be storing our files) by passing in NSMetadataQueryUbiquitousDocumentsScope as the search scope.

You can then filter the output with a predicate. We set up one here to look for files that end with the PTK extension.

Next let’s create some methods to start and stop this query. Make the following changes to PTKMasterViewController.m:

// Add new private instance variables
NSMetadataQuery * _query;
BOOL _iCloudURLsReady;
NSMutableArray * _iCloudURLs;
 
// Add to "iCloud query" section after documentQuery method, replacing the existing startQuery method
- (void)stopQuery {
 
    if (_query) {
 
        NSLog(@"No longer watching iCloud dir...");
 
        [[NSNotificationCenter defaultCenter] removeObserver:self name:NSMetadataQueryDidFinishGatheringNotification object:nil];
        [[NSNotificationCenter defaultCenter] removeObserver:self name:NSMetadataQueryDidUpdateNotification object:nil];
        [_query stopQuery];
        _query = nil;
    }
 
}
 
- (void)startQuery {
 
    [self stopQuery];
 
    NSLog(@"Starting to watch iCloud dir...");
 
    _query = [self documentQuery];
 
    [[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(processiCloudFiles:)
                                                 name:NSMetadataQueryDidFinishGatheringNotification
                                               object:nil];
    [[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(processiCloudFiles:)
                                                 name:NSMetadataQueryDidUpdateNotification
                                               object:nil];
 
    [_query startQuery];
}
 
// Add in viewDidLoad before call to refresh
_iCloudURLs = [[NSMutableArray alloc] init];
 
// Add at beginning of refresh method
_iCloudURLsReady = NO;
[_iCloudURLs removeAllObjects];

startQuery gets the query and starts it up. It also registers for two notifications – the initial gather notification, as well as further updates. In both cases, processiCloudFiles will be called – we’ll write that next. stopQuery just does the opposite and tears things down.

Continue by adding the implementation of processiCloudFiles:

- (void)processiCloudFiles:(NSNotification *)notification {
 
    // Always disable updates while processing results
    [_query disableUpdates];
 
    [_iCloudURLs removeAllObjects];
 
    // The query reports all files found, every time.
    NSArray * queryResults = [_query results];
    for (NSMetadataItem * result in queryResults) {
        NSURL * fileURL = [result valueForAttribute:NSMetadataItemURLKey];
        NSNumber * aBool = nil;
 
        // Don't include hidden files
        [fileURL getResourceValue:&aBool forKey:NSURLIsHiddenKey error:nil];
        if (aBool && ![aBool boolValue]) {
            [_iCloudURLs addObject:fileURL];
        }        
 
    }        
 
    NSLog(@"Found %d iCloud files.", _iCloudURLs.count);
    _iCloudURLsReady = YES;
 
    if ([self iCloudOn]) {
 
        // Remove deleted files
        // Iterate backwards because we need to remove items form the array
        for (int i = _objects.count -1; i >= 0; --i) {
            PTKEntry * entry = [_objects objectAtIndex:i];
            if (![_iCloudURLs containsObject:entry.fileURL]) {
                [self removeEntryWithURL:entry.fileURL];
            }
        }
 
        // Add new files
        for (NSURL * fileURL in _iCloudURLs) {                
            [self loadDocAtURL:fileURL];        
        }
 
        self.navigationItem.rightBarButtonItem.enabled = YES;
 
    } 
 
    [_query enableUpdates];
 
}

When you’re processing the results of an NSMetadataQuery, it’s important to stop the query so you don’t get more updates while you’re in the middle of processing the first, so we do that at the beginning and end of the method.

We then loop through the query results, and add everything to the list except for items that are hidden. We add all of the results to the most up-to-date list of _iCloudURLs, which we will find handy later, and set a flag indicating that they are ready.

If iCloud isn’t on, that’s all we do. But if it is on, we make sure our local list of entries matches the list of iCloud files. We first loop through our entries and remove anything not in the list of iCloud files by calling removeEntryWithURL. We also add anything that isn’t already in the list to the list by calling loadDocAtURL. When this is all done it’s safe to add a new document again, so we enable the right bar button item.

Next, add these methods right after viewDidUnload:

- (void)viewWillAppear:(BOOL)animated {
    [_query enableUpdates];
}
 
- (void)viewWillDisappear:(BOOL)animated {
    [_query disableUpdates];
}

This is important to add because UIDocument has issues if you try to open more than instance at a time pointing to the same fileURL, so we don’t want our table view trying to refresh itself (hence loading a UIDocument to get its medatata) while we’re editing a document.

We could run the app now but there wouldn’t be any use, as there’s no way to create a file in iCloud yet. Luckily, since we already laid most of the groundwork by using UIDocument this is quite easy to fix! Simply replace getDocURL with the following:

- (NSURL *)getDocURL:(NSString *)filename {    
    if ([self iCloudOn]) {
        NSURL * docsDir = [_iCloudRoot URLByAppendingPathComponent:@"Documents" isDirectory:YES];
        return [docsDir URLByAppendingPathComponent:filename];
    } else {
        return [self.localRoot URLByAppendingPathComponent:filename];    
    }
}

Here we’ve implemented the “iCloudOn” case to return the Documents subdirectory of the iCloud root, where we will be saving our files.

When we go to create a new file, now it will be creating it in the iCloud directory, so the daemon will pick up on it and synchronize it. Everything else will just work since we’re using UIDocument!

Compile and run on your device, and make sure iCloud is available and switched on. Create some documents and verify that they are created in the iCloud directory by looking at the logs.

Now for the fun part – start up a second device and you should see the same files pull down from iCloud! :D

If you have any troubles, try deleting the app from your device and re-installing, double checking that your Document exports are set up properly, or compare your project to the solution at the end of this tutorial.

Fixing Deleting

If you try deleting a file right now, it may work, but it’s currently doing things in an unsafe way according to the Document-Based App Programming Guide.

When you’re dealing with files in an iCloud directory, you can’t just use NSFileManager APIs directly like you could with local files. Instead, you have to use the NSFileCoordinator class to make sure it’s safe to modify the files. This is important since the iCloud daemon is also working with this directory at the same time.

To see what this looks like, open PTKMasterViewController.m and replace deleteEntry with the following:

- (void)deleteEntry:(PTKEntry *)entry {
 
    // Wrap in file coordinator
    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^(void) {
        NSFileCoordinator* fileCoordinator = [[NSFileCoordinator alloc] initWithFilePresenter:nil];
        [fileCoordinator coordinateWritingItemAtURL:entry.fileURL 
                                            options:NSFileCoordinatorWritingForDeleting
                                              error:nil 
                                         byAccessor:^(NSURL* writingURL) {                                                   
                                             // Simple delete to start
                                             NSFileManager* fileManager = [[NSFileManager alloc] init];
                                             [fileManager removeItemAtURL:entry.fileURL error:nil];
                                         }];
    });    
 
    // Fixup view
    [self removeEntryWithURL:entry.fileURL];
 
}
 
-

Here we create a NSFileCoordinator and use the coordinateWritingAtURL method passing in NSFileCoordinatorWritingForDeletign to make sure we have access to delete the file. This method may block, so it’s important to run it on a background thread. Once we have access, it’s safe to delete it as usual.

Compile and run, and now you should be able to delete entries – but safely this time!

Fixing Renaming

Similarly, we need to fix up renaming. In the renameEntry method, replace the “Simple renaming to start” section with the following:

// Wrap in file coordinator
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^(void) {
    NSError * error;
    NSFileCoordinator *coordinator = [[NSFileCoordinator alloc] initWithFilePresenter:nil];
    [coordinator coordinateWritingItemAtURL:entry.fileURL options: NSFileCoordinatorWritingForMoving writingItemAtURL:newDocURL options: NSFileCoordinatorWritingForReplacing error:&error byAccessor:^(NSURL *newURL1, NSURL *newURL2) {
 
        // Simple renaming to start
        NSFileManager* fileManager = [[NSFileManager alloc] init];
        NSError * error;
        BOOL success = [fileManager moveItemAtURL:entry.fileURL toURL:newDocURL error:&error];
        if (!success) {
            NSLog(@"Failed to move file: %@", error.localizedDescription);
            return;
        }
 
    }];
});

This is exactly the same as we did for deleting files, except we call a slightly different method on NSFileCoordinator with parameters for moving a file.

Compile and run, and try to create a file, and… wait, it doesn’t work! The console shows the following:

Failed to move file: The operation couldn’t be completed. (Cocoa error 4.)

To be honest, I have no idea why we get this error – it seems to me that this should work. If anyone knows (maybe I have passed the wrong parameters to coordinateWritingItemAtURL:entry.fileURL?) let me know.

In the meantime, I have another method that works (although is slightly hackish) – save the old file to a new filename, and delete the old file. Try it out by replacing the above code block with the following:

// Rename by saving/deleting - hack?
NSURL * origURL = entry.fileURL;
UIDocument * doc = [[PTKDocument alloc] initWithFileURL:entry.fileURL];
[doc openWithCompletionHandler:^(BOOL success) {
    [doc saveToURL:newDocURL forSaveOperation:UIDocumentSaveForCreating completionHandler:^(BOOL success) {
        NSLog(@"Doc saved to %@", newDocURL);                        
        [doc closeWithCompletionHandler:^(BOOL success) {
 
            // Update version of file
            dispatch_async(dispatch_get_main_queue(), ^{
                entry.version = [NSFileVersion currentVersionOfItemAtURL:newDocURL];
                int index = [self indexOfEntryWithFileURL:entry.fileURL];
                [self.tableView reloadRowsAtIndexPaths:[NSArray arrayWithObject:[NSIndexPath indexPathForRow:index inSection:0]] withRowAnimation:UITableViewRowAnimationNone];    
            });                
 
            // Delete old file
            dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^(void) {
                NSFileCoordinator* fileCoordinator = [[NSFileCoordinator alloc] initWithFilePresenter:nil];
                [fileCoordinator coordinateWritingItemAtURL:origURL 
                                                    options:NSFileCoordinatorWritingForDeleting
                                                      error:nil 
                                                 byAccessor:^(NSURL* writingURL) {                                                   
                                                     NSFileManager* fileManager = [[NSFileManager alloc] init];
                                                     [fileManager removeItemAtURL:writingURL error:nil];
                                                 }];
            });
            NSLog(@"Doc deleted at %@", origURL);
        }];
    }];
}];

Compile and run, and you should now be able to rename files at will!

Note that the way the app is currently designed, when you rename a file it will disappear temporarily (because the old file was deleted) and reappear a second later (as the new file is noticed and opened). This is because our table view is refreshed upon the results of the NSMetadataQuery. If anyone has a better strategy to deal with updates to avoid this problem, please drop a note in the forum discussion!

Detecting Updates

The last thing we’ll cover in this part of the tutorial is detecting updates to an opened document. Right now, if you open the same document on two devices and change the photo on one of the devies, the other device won’t notice that it’s changed.

Luckily, UIDocument has built-in support to notice changes and update itself behind the scenes! All we need to do is register for a notification when this occurs so we can update the detail view controller.

Open PTKDetailViewController.m and add these methods right after shouldAutorotateToInterfaceOrientation:

- (void)viewWillAppear:(BOOL)animated {
 
    [[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(documentStateChanged:)
                                                 name:UIDocumentStateChangedNotification 
                                               object:self.doc];
 
}
 
- (void)viewWillDisappear:(BOOL)animated {
    [[NSNotificationCenter defaultCenter] removeObserver:self];
}
 
- (void)documentStateChanged:(NSNotification *)notificaiton {
 
    [self configureView];
 
}

Here we just wait for the UIDocumentStateChangedNotification notification and refresh the view if it occurs. Pretty simple, eh?

Compile and run on two devices, and open the same document on two devices. Now when you modify the document on device 1, the second device will notice and update as well!

Where To Go From Here?

Here is a download with the state of the code sample so far.

At this point, this app is fully functional for local documents, mostly functional for iCloud documents (with full create, read, update, delete support), and allows you to toggle back and forth between the two options in Settings.

However, there are still some subtle aspects remaining that we need to address. We need to implement those methods to move documents to and from iCloud when the user switches iCloud on or off, and we need to deal with the dreaded iCloud conflicts!

So stay tuned for the final part of this tutorial series, where we will cover those topics. In the meantime, if you have any comments, questions, or suggestions for improvement please join the forum discussion below!

This is a blog post by site administrator Ray Wenderlich, an independent software developer and gamer.

iCloud and UIDocument: Beyond the Basics. Part 3/4 is a post from: Ray Wenderlich

Learn how to make a complete UIDocument + iCloud app!

This is a blog post by site administrator Ray Wenderlich, an independent software developer and gamer.

Welcome back to our document-based iCloud app tutorial series!

In this tutorial series we are making a complete document-based iCloud app called PhotoKeeper, with features that go beyond just the basics.

In the first part of the series, we created model classes for our app and a UIDocument wrapper. We also added logic to list and add local files.

In this second part of the series, we will make the app fully functional when it comes to local files. We will improve the look of our master view, implement the detail view, and add support for renaming and deleting files.

If you’re eager to get into iCloud, don’t worry – getting UIDocument support working like we’re doing here is a prerequisite! We’re laying a framework that will make switching to iCloud much easier.

This project continues where we left off last time, so if you don’t have it already grab the previous code sample and open up the project. Let’s begin!

A Better Table View

Right now our table view is the boring default style that the template made for us. Let’s fix this up so it’s more the way we want for PhotoKeeper.

Open MainStoryboard.storyboard and select the Table View inside the Master View Controller. Switch to the Size Inspector, and set the Row Height to 80:

Next select the Table View Cell and set the Style to Custom to remove the default controls:

Drag a UIImageView, UITextField, and UILabel into the cell so it looks roughly like the following:

Note we are adding a UITextField instead of a UILabel for the document name so that later we can implement renaming the document.

Speaking of the UITextField – select it and go to the Attributes Inspector. Set the Border Style to None, Clear Button to Appears while editing, the Font to System 17.0, Capitalization to Words, and Correction to No:

To nicely support landscape orientation, set the autosizing attributes of the text field and label as follows:

To fill in our controls, we need a way to access them via code. We could get them from the cell by tag, but to keep our code cleaner and easier to read we will make a custom UITableView sublass instead.

Create a new file with the iOS\Cocoa Touch\Objective-C class template, name it PTKEntryCell, and make it a subclass of UITableViewCell. Then replace the contents of PTKEntryCell.h with the following:

#import <UIKit/UIKit.h>
 
@interface PTKEntryCell : UITableViewCell
 
@property (weak, nonatomic) IBOutlet UIImageView * photoImageView;
@property (weak, nonatomic) IBOutlet UITextField * titleTextField;
@property (weak, nonatomic) IBOutlet UILabel * subtitleLabel;
 
@end

Here we make outlets for the controls in our cell, and also add a delegate that we can notify when the user edits the text.

While you’re at it switch to PTKEntryCell.m and replace the contents with the following:

#import "PTKEntryCell.h"
 
@implementation PTKEntryCell
@synthesize photoImageView;
@synthesize titleTextField;
@synthesize subtitleLabel;
 
- (void)setEditing:(BOOL)editing animated:(BOOL)animated
{
    [super setEditing:editing animated:animated];
 
    [UIView animateWithDuration:0.1 animations:^{
        if(editing){
            titleTextField.enabled = YES;
            titleTextField.borderStyle = UITextBorderStyleRoundedRect;
        }else{
            titleTextField.enabled = NO;
            titleTextField.borderStyle = UITextBorderStyleNone;
        }
    }];
 
}
 
@end

Here we implement setEditing in order to switch our text field into editing mode or not based on whether the cell is in editing mode.

Now let’s configure our table view to use this custom cell class in the Storyboard editor. Open MainStoryboard.storyboard, select the cell, and in the identity inspector set it to PTKEntryCell:

Now control-drag from the cell to the image view, text field, and label controls, connecting them to the photoImageView, titleTextField, and subtitleLabel outlets.

Let’s set up the master view controller to use this cell now. Open PTKMasterViewController.h and mark the class as implementing UITextFieldDelegate:

#import <UIKit/UIKit.h>
 
@interface PTKMasterViewController : UITableViewController <UITextFieldDelegate>
 
@end

Then switch to PTKMasterViewController.m and import PTKEntryCell.h at the top of the file:

#import "PTKEntryCell.h"

And replace tableView:cellForRowAtIndexPath: with the following:

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
    PTKEntryCell *cell = [tableView dequeueReusableCellWithIdentifier:@"Cell"];
 
    PTKEntry *entry = [_objects objectAtIndex:indexPath.row];
 
    cell.titleTextField.text = entry.description;
    cell.titleTextField.delegate = self;
    if (entry.metadata && entry.metadata.thumbnail) {
        cell.photoImageView.image = entry.metadata.thumbnail;
    } else {
        cell.photoImageView.image = nil;
    }
    if (entry.version) {
        cell.subtitleLabel.text = [entry.version.modificationDate mediumString];
    } else {
        cell.subtitleLabel.text = @"";
    }
 
    return cell;
}

This is similar to what we had before, except we are setting the controls in our new PTKEntryCell. We’ll implement the delegate callback later so don’t worry about it for now.

That’s it – compile and run, and now the app’s looking a bit better!

It doesn’t show photos yet (since we had no way to set photos), but that’s what we’ll do next :]

Creating the Detail View

Right now our detail view doesn’t work – it’s just the default detail view created for us by the template. Let’s fix that up.

Open MainStoryboard.storyboard and find the Detail View Controller. Delete the label that’s in the middle, and add a big old UIImageView filling up the entire view:

Open up the Assistant Editor, make sure that PTKDetailViewController.h is visible in the assistant editor, and control-drag from the image view below the @interface. Enter imageView for the name, and click Connect.

Next switch to PTKDetailViewController.h and modify the file so it looks like the following:

#import <UIKit/UIKit.h>
 
@class PTKDocument;
@class PTKDetailViewController;
 
@protocol PTKDetailViewControllerDelegate 
- (void)detailViewControllerDidClose:(PTKDetailViewController *)detailViewController;
@end
 
@interface PTKDetailViewController : UIViewController <UIImagePickerControllerDelegate, UINavigationControllerDelegate>
 
@property (strong, nonatomic) PTKDocument * doc;
@property (weak, nonatomic) IBOutlet UIImageView *imageView;
@property (weak) id <PTKDetailViewControllerDelegate> delegate;
 
@end

Here we added a protocol/delegate which we can notify when the user is done, added a property of the (opened) PTKDocument we should display, and marked our class as implementing two protocols we’ll need to use an image picker.

Note that we are passing an opened PTKDocument as the item to display (rather than the fileURL). This was a design decision. It can take time to open a document, especially if it is large or not fully synchronized with iCloud, and it depends where you want to spend that time – before transitioning to the detail view or after. We chose before for this.

Next switch to PTKDetailViewController.m and replace it with the following. Note I am giving a lot of code at once here, but this is pretty simple stuff so it should be OK.

#import "PTKDetailViewController.h"
#import "PTKDocument.h"
#import "PTKData.h"
#import "UIImageExtras.h"
 
@interface PTKDetailViewController ()
- (void)configureView;
@end
 
@implementation PTKDetailViewController {
    UIImagePickerController * _picker;
}
 
@synthesize doc = _doc;
@synthesize imageView = _imageView;
@synthesize delegate = _delegate;
 
#pragma mark - Managing the detail item
 
- (void)setDoc:(id)newDoc
{
    if (_doc != newDoc) {
        _doc = newDoc;
 
        // Update the view.
        [self configureView];
    }
}
 
- (void)configureView
{
    // Update the user interface for the detail item.
    self.title = [self.doc description];
    if (self.doc.photo) {
        self.imageView.image = self.doc.photo;
    } else {
        self.imageView.image = [UIImage imageNamed:@"defaultImage.png"];
    }
}
 
- (void)viewDidLoad
{
    [super viewDidLoad];
	// Do any additional setup after loading the view, typically from a nib.
 
    UIBarButtonItem *backButtonItem = [[UIBarButtonItem alloc] initWithBarButtonSystemItem:UIBarButtonSystemItemDone target:self action:@selector(doneTapped:)];
    self.navigationItem.leftBarButtonItem = backButtonItem;
    [self.navigationItem setHidesBackButton:YES animated:YES];
 
    UITapGestureRecognizer * tapRecognizer = [[UITapGestureRecognizer alloc] initWithTarget:self action:@selector(imageTapped:)];
    [self.view addGestureRecognizer:tapRecognizer];
 
    [self configureView];
}
 
- (void)viewDidUnload
{
    [self setImageView:nil];
    [super viewDidUnload];
}
 
- (BOOL)shouldAutorotateToInterfaceOrientation:(UIInterfaceOrientation)interfaceOrientation
{
    return (interfaceOrientation != UIInterfaceOrientationPortraitUpsideDown);
}
 
#pragma mark Callbacks
 
- (void)imageTapped:(UITapGestureRecognizer *)recognizer {
    if (!_picker) {
        _picker = [[UIImagePickerController alloc] init];
        _picker.delegate = self;
        _picker.sourceType = UIImagePickerControllerSourceTypePhotoLibrary;
        _picker.allowsEditing = NO;
    }
 
    [self presentModalViewController:_picker animated:YES];
}
 
- (void)doneTapped:(id)sender {
 
    NSLog(@"Closing %@...", self.doc.fileURL);
 
    [self.doc saveToURL:self.doc.fileURL forSaveOperation:UIDocumentSaveForOverwriting completionHandler:^(BOOL success) {
        [self.doc closeWithCompletionHandler:^(BOOL success) {
            dispatch_async(dispatch_get_main_queue(), ^{                        
                if (!success) {
                    NSLog(@"Failed to close %@", self.doc.fileURL);
                    // Continue anyway...
                }
 
                [self.delegate detailViewControllerDidClose:self];
            });
        }];
    }];
 
}
 
#pragma mark UIImagePickeerControllerDelegate
 
- (void)imagePickerControllerDidCancel:(UIImagePickerController *)picker {
 
    [self dismissViewControllerAnimated:YES completion:nil];
 
}
 
- (void)imagePickerController:(UIImagePickerController *)picker didFinishPickingMediaWithInfo:(NSDictionary *)info {    
 
    UIImage *image = (UIImage *) [info objectForKey:UIImagePickerControllerOriginalImage];
 
    CGSize mainSize = self.imageView.bounds.size;
    UIImage *sImage = [image imageByBestFitForSize:mainSize]; //[image scaleToFitSize:mainSize];
 
    self.doc.photo = sImage;
    self.imageView.image = sImage;
 
    [self dismissViewControllerAnimated:YES completion:nil];
 
}
 
@end

Read through this and make sure you understand what’s going on. There are just a few things to point out here:

• When the user changes the image, we change it in the document immediately via the setter we wrote earlier. Since the setter uses the undo manager, UIDocument knows about the change so will auto-save the document at some point in the future.
• When the done button is tapped, we close the document. This triggers a save if it hasn’t been auto-saved already. We notify the delegate when we’re done so they can dismiss us.

Almost done – just need to make the master view controller use this. First, right now the template has made is so when a row is tapped a segue is automatically performed (bypassing tableView:didSelectRowAtIndexPath). We first need to modify this so tableView:didSelectRowAtIndexPath is called first, so we have a chance to open the document before performing the segue.

To fix this, open MainStoryboard.storyboard and delete the segue between the master view controller and the detail view controller. Then control-drag from the master view controller (NOT the table view cell) to the detail view controller, and choose Push from the segue popup. Then select the segue and name it showDetail:

Next open PTKMasterViewController.h and mark the class as implementing the detail view controller delegate:

#import <UIKit/UIKit.h>
#import "PTKEntryCell.h"
#import "PTKDetailViewController.h"
 
@interface PTKMasterViewController : UITableViewController <UITextFieldDelegate, PTKDetailViewControllerDelegate>
 
@end

Then switch to PTKMasterViewController.m and make the following changes:

// 1) Add right above the "View lifecycle" section with awakeFromNib
#pragma mark PTKDetailViewControllerDelegate
 
- (void)detailViewControllerDidClose:(PTKDetailViewController *)detailViewController {
    [self.navigationController popViewControllerAnimated:YES];
    NSFileVersion * version = [NSFileVersion currentVersionOfItemAtURL:detailViewController.doc.fileURL];
    [self addOrUpdateEntryWithURL:detailViewController.doc.fileURL metadata:detailViewController.doc.metadata state:detailViewController.doc.documentState version:version];
}
 
// 2) Add right above prepareForSegue
- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath {
 
    PTKEntry * entry = [_objects objectAtIndex:indexPath.row];
    [self.tableView deselectRowAtIndexPath:indexPath animated:YES];
 
    _selDocument = [[PTKDocument alloc] initWithFileURL:entry.fileURL];    
    [_selDocument openWithCompletionHandler:^(BOOL success) {
        dispatch_async(dispatch_get_main_queue(), ^{
            [self performSegueWithIdentifier:@"showDetail" sender:self];
        });
    }];            
 
}
 
// 3) Replace prepareForSegue with the following
- (void)prepareForSegue:(UIStoryboardSegue *)segue sender:(id)sender
{
    if ([[segue identifier] isEqualToString:@"showDetail"]) {
        [[segue destinationViewController] setDelegate:self];
        [[segue destinationViewController] setDoc:_selDocument];
    } 
}

Let’s go through these methods one by one:

1. When the detail view is done, we pop the view controller and refresh our table view entry.
2. When a row is selected, we open the document and perform the segue once it’s loaded.
3. When a segue is performed, we pass the document to be edited to the detail view, and also set ourselves as its delegate.

If you’re still rusty with the concept of segues, you might want to check out our storyboard tutorial.

That’s it! Compile and run, and now you can set photos on your documents and they will persist even if you shut down/restart the app!

Deleting Documents

Hey, we’re getting pretty close to a functional app here! But right now although we can create files, we can’t delete flies. Let’s add that real quick.

Make the following changes to PTKMasterViewController.m:

// Add to end of "Entry management methods" section
- (void)removeEntryWithURL:(NSURL *)fileURL {
    int index = [self indexOfEntryWithFileURL:fileURL];
    [_objects removeObjectAtIndex:index];
    [self.tableView deleteRowsAtIndexPaths:[NSArray arrayWithObject:[NSIndexPath indexPathForRow:index inSection:0]] withRowAnimation:UITableViewRowAnimationLeft];
}
 
// Add at end of "File management methods" section
- (void)deleteEntry:(PTKEntry *)entry {
 
    // Simple delete to start
    NSFileManager* fileManager = [[NSFileManager alloc] init];
    [fileManager removeItemAtURL:entry.fileURL error:nil];
 
    // Fixup view
    [self removeEntryWithURL:entry.fileURL];
 
}
 
// Replace tableView:commitEditingStyle:forRowAtIndexPath
- (void)tableView:(UITableView *)tableView commitEditingStyle:(UITableViewCellEditingStyle)editingStyle forRowAtIndexPath:(NSIndexPath *)indexPath
{
    if (editingStyle == UITableViewCellEditingStyleDelete) {                
        PTKEntry * entry = [_objects objectAtIndex:indexPath.row];
        [self deleteEntry:entry];        
    } 
}

The only part worth mentioning here is the delete itself is performed by NSFileManager’s removeItemAtURL method. This will cause problems with iCloud as-is but will work fine for local docs, so we’ll keep it this way for now.

Compile and run, and now you can swipe rows to permanently delete them! Be sure to shut down and restart the app to verify they are gone for good.

Renaming Documents

Next we need to add a way for users to rename their files rather than always having “Photo”, “Photo 1″, etc.

First let’s add a method to rename an entry to a given filename. Add this method to PTKMasterViewController.m to the “Entry management methods” section, right below addOrUpdateEntryWithURL:metadata:state:version:

- (BOOL)renameEntry:(PTKEntry *)entry to:(NSString *)filename {
 
    // Bail if not actually renaming
    if ([entry.description isEqualToString:filename]) {
        return YES;
    }
 
    // Check if can rename file
    NSString * newDocFilename = [NSString stringWithFormat:@"%@.%@",
                                 filename, PTK_EXTENSION];
    if ([self docNameExistsInObjects:newDocFilename]) {
        NSString * message = [NSString stringWithFormat:@"\"%@\" is already taken.  Please choose a different name.", filename];
        UIAlertView * alertView = [[UIAlertView alloc] initWithTitle:nil message:message delegate:nil cancelButtonTitle:nil otherButtonTitles:@"OK", nil];
        [alertView show];
        return NO;
    }
 
    NSURL * newDocURL = [self getDocURL:newDocFilename];
    NSLog(@"Moving %@ to %@", entry.fileURL, newDocURL);
 
    // Simple renaming to start
    NSFileManager* fileManager = [[NSFileManager alloc] init];
    NSError * error;
    BOOL success = [fileManager moveItemAtURL:entry.fileURL toURL:newDocURL error:&error];
    if (!success) {
        NSLog(@"Failed to move file: %@", error.localizedDescription);
        return NO;
    }    
 
    // Fix up entry
    entry.fileURL = newDocURL;
    int index = [self indexOfEntryWithFileURL:entry.fileURL];
    [self.tableView reloadRowsAtIndexPaths:[NSArray arrayWithObject:[NSIndexPath indexPathForRow:index inSection:0]] withRowAnimation:UITableViewRowAnimationNone];
 
    return YES;
 
}

This checks if the name is available (and warns the user if not), and otherwise moves the file using NSFileManager’s moveItemAtURL API. This particular API has problems when it comes to iCloud (which we’ll discuss later) but works quite fine with local files so we’ll keep it that way.

Now let’s call this method when the user renames a file by modify the text field of a cell while in edit mode. Remember how we added a delegate to the UITableViewCell to notify us when the user changes the text for the filename, but never implemented it? Now’s the time!

Add the following code right above the “View lifecycle” section with awakeFromNib:

#pragma mark Text Views
 
- (void)textChanged:(UITextField *)textField {
    UIView * view = textField.superview;
    while( ![view isKindOfClass: [PTKEntryCell class]]){
        view = view.superview;
    }
    PTKEntryCell *cell = (PTKEntryCell *) view;
    NSIndexPath * indexPath = [self.tableView indexPathForCell:cell];
    PTKEntry * entry = [_objects objectAtIndex:indexPath.row];
    NSLog(@"Want to rename %@ to %@", entry.description, textField.text);
    [self renameEntry:entry to:textField.text];
}
 
- (BOOL)textFieldShouldReturn:(UITextField *)textField {
	[textField resignFirstResponder];
    [self textChanged:textField];
	return YES;
}

Pretty simple, eh? Compile and run, and now you can rename files!

Bonus: Scrolling Fix

If you have a lot of photos, you might notice that if you tap on a text field toward the bottom of the table view, the keybaord overlaps it so you can’t see what you’re editing. That’s kind of annoying, eh?

Here’s a quick fix courtesy of ZeLogolas on StackOverflow. Make the following changes to PTKMasterViewController.m:

// Add private instance variable
UITextField * _activeTextField;
 
// Add inside "Text Views" section, above textChanged
-(void) keyboardWillShow:(NSNotification *)note
{
    // Get the keyboard size
    CGRect keyboardBounds;
    [[note.userInfo valueForKey:UIKeyboardFrameBeginUserInfoKey] getValue: &keyboardBounds];
 
    // Detect orientation
    UIInterfaceOrientation orientation = [[UIApplication sharedApplication] statusBarOrientation];
    CGRect frame = self.tableView.frame;
 
    // Start animation
    [UIView beginAnimations:nil context:NULL];
    [UIView setAnimationBeginsFromCurrentState:YES];
    [UIView setAnimationDuration:0.3f];
 
    // Reduce size of the Table view 
    if (orientation == UIInterfaceOrientationPortrait || orientation == UIInterfaceOrientationPortraitUpsideDown)
        frame.size.height -= keyboardBounds.size.height;
    else 
        frame.size.height -= keyboardBounds.size.width;
 
    // Apply new size of table view
    self.tableView.frame = frame;
 
    // Scroll the table view to see the TextField just above the keyboard
    if (_activeTextField)
    {
        CGRect textFieldRect = [self.tableView convertRect:_activeTextField.superview.bounds fromView:_activeTextField.superview];
        [self.tableView scrollRectToVisible:textFieldRect animated:NO];
    }
 
    [UIView commitAnimations];
}
 
-(void) keyboardWillHide:(NSNotification *)note
{
    // Get the keyboard size
    CGRect keyboardBounds;
    [[note.userInfo valueForKey:UIKeyboardFrameBeginUserInfoKey] getValue: &keyboardBounds];
 
    // Detect orientation
    UIInterfaceOrientation orientation = [[UIApplication sharedApplication] statusBarOrientation];
    CGRect frame = self.tableView.frame;
 
    [UIView beginAnimations:nil context:NULL];
    [UIView setAnimationBeginsFromCurrentState:YES];
    [UIView setAnimationDuration:0.3f];
 
    // Reduce size of the Table view 
    if (orientation == UIInterfaceOrientationPortrait || orientation == UIInterfaceOrientationPortraitUpsideDown)
        frame.size.height += keyboardBounds.size.height;
    else 
        frame.size.height += keyboardBounds.size.width;
 
    // Apply new size of table view
    self.tableView.frame = frame;
 
    [UIView commitAnimations];
}
 
- (IBAction)textFieldDidBeginEditing:(UITextField *)textField
{
    _activeTextField = textField;
}
 
- (IBAction)textFieldDidEndEditing:(UITextField *)textField
{
    _activeTextField = nil;
}
 
// Add at bottom of viewDidLoad
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(keyboardWillShow:) name:UIKeyboardWillShowNotification object:nil];
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(keyboardWillHide:) name:UIKeyboardWillHideNotification object:nil];
 
// Add at bottom of viewDidUnload
[[NSNotificationCenter defaultCenter] removeObserver:self];

Compile and run, and it will now auto-scroll if you select an item at the bottom!

Where To Go From Here?

Here is a download with the state of the code sample so far.

At this point you have a fully functional UIDocument based app that stores documents locally. You have now laid the groundwork that will make adding iCloud support much easier!

In the next part of the series, we’ll finally get to iCloud itself! We’ll get the basics working, and then in the final part of the series we’ll cover more advanced aspects like moving files to/from iCloud, handling conflicts, and more.

If you have any questions, comments, or suggestions about better ways to do things, please join the forum discussion below! :]

This is a blog post by site administrator Ray Wenderlich, an independent software developer and gamer.

iCloud and UIDocument: Beyond the Basics. Part 2/4 is a post from: Ray Wenderlich

Learn how to make a complete UIDocument + iCloud app!

This is a blog post by site administrator Ray Wenderlich, an independent software developer and gamer.

Creating a document-based iCloud app is complicated. There’s a lot of different things to think about, and it’s easy to forget to implement something out or make a mistake along the way.

There are several tutorials on creating iCloud apps out there, including Apple’s Your Third iOS App tutorial and our own iOS 5 by Tutorials, which do a great job of explaining the basics of using iCloud.

What we really need is a tutorial that goes beyond the basics and puts everything together into a complete app that you (gasp) might actually be able to use. This is my attempt to put something like that together for you guys!

In this tutorial, we’re going to create a simple iCloud document based app called PhotoKeeper. It will show you how to do the following:

• Create, Read, Update, and Delete documents – both on iCloud *and* locally
• Create documents consisting of multiple files with NSFileWrapper
• Give previews of documents in the master view in an efficient manner
• Allow a toggle for the user to enable/disable iCloud in Settings
• Move/copy files to and from iCloud when user switches
• Alllow renaming and deleting files – the safe way
• Deal with conflicts and document updates

This is a four part tutorial series. In the first two parts we’ll get things working for local documents only, and then in the second two parts we’ll add iCloud support.

Are you ready to see how to put everything together with iCloud? Let’s get started!

Choosing our iCloud Storage Method

In this tutorial, we are going to create a simple app called PhotoKeeper that allows users to store and name their favorite photos either locally or in iCloud.

There are three main ways an app can store its data in iCloud. Which should we choose for this app?

1. Use Key/Value Store. iCloud has an extremely easy to use helper class called NSUbiquitousKeyValueStore that is very similar to NSUserDefaults. If your app has a small amount of data to store (< 1 MB), this method is usually the best choice.
2. Use Core Data. You can set up Core Data to store its data on iCloud. If your app doesn’t have the concept of documents or files but has a large amount of data, this method is usually the best choice.
3. Create a Document-Based App. The final method is to create a document based app by subclassing a class called UIDocument. If your app is based around the concept of individual documents that the user can create/read/update/delete that you want listed as separate files in Settings, this method is usually the best choice.

For PhotoKeeper, the third option makes the most sense. We want each photo treated as a separate unit/document/file that we can see in iCloud storage separately.

If you think Key/Value Storage or iCloud makes more sense for your app, check out iOS 5 by Tutorials, where we have some examples and more details on those techniques.

iCloud Document-Based App Overview

Next let’s give an overview of what it takes to make an iCloud Document-Based App, and some design choices we’re going to make for PhotoKeeper along the way. We will cover five topics:

1. How it Works
2. Subclassing UIDocument
3. Input/Output Formats
4. Local vs. iCloud
5. Storage Philosophy

1) How it Works

At a very high level, here’s how iCloud and UIDocument works.

If iCloud is available and your app is configured to use iCloud, your app can access a special directory on the device. Whatever you put in this directory will be automatically synchronized to iCloud by a system daemon.

You can’t just enumerate this directory with normal APIs – you have to use a special API we’ll discuss later. You also have to be careful about accessing files in this directory, because the the iCloud daemon is also working with the files at the same time.

The easiest way to work with these files is by subclassing a class called UIDocument. It takes care most of the details for you (such as coordinating with the iCloud daemon and more), and allows you to focus primarily on what matters to you – your app’s data!

For more details on how iCloud works, check out the the iOS App Programming Guide: iCloud Storage.

Via Apple's iOS Programming Guide.

2) Subclassing UIDocument

When you subclass UIDocument you need to overrride two methods:

• loadFromContents:ofType:error: Think of this as “read the document”. You get an input class, and you have to decode it to your internal model.
• contentsForType:error: Think of this as “write the document”. You encode your internal model to an output class.

It’s usually best if your UIDocument class contains a reference to your app’s model class, which can be just a plain old NSObject. If your model object supports NSCoding (tutorial here), implementing these methods is trivial.

For this tutorial, we’ve kept our document’s data model very simple – it’s literally jsut a photo! However, you can use this same technique we’re demonstrating in this tutorial no matter how complex or large your docuemnt is.

3) Input/Output Formats

UIDocument supports two different classes for input/output:

• NSData. This represents a simple buffer of data, which is good when your document is just a single file.
• NSFileWrapper. This represents a directory of file packages, which the OS treats as a single file. This is good for when your document consists of multiple files that you want to be able to load independently.

At first glance, it might seem that using NSData would make the most sense, since our document is just a simple photo.

However, one of the design goals of PhotoKeeper is to show a thumbnail of the photo in the master view controller before the user opens a file. If we used NSData, to get the thumbnails we’d have to open and decode every single document from the disk. Since the images can be quite large, this could lead to slow performance and high memory overhead.

So what we’re going to do instead is use NSFileWrapper. We’ll store two documents inside the wrapper:

1. The main data. This will be the main data of the document. For PhotoKeeper, this will be our full size photo.
2. The metadata. This will be anything the master view controller needs to display a preview. It should be a small amount of data that can be loaded quickly. For PhotoKeeper, this will be a small (resized) thumbnail of the photo.

This way the master view controller only needs to load each photo’s (small) metadata sub-file inside the NSWrapper instead of the entire (large) data sub-file. It might not make a huge difference in this tutorial, but the larger your document’s data file becomes the more useful this is!

4) Local vs. iCloud

It’s not enough to make an app that is just iCloud enabled – it also has to work without iCloud too!

This is because the user might not have iCloud enabled on their device, or may want to turn iCloud off specifically for your app.

One of the nice things about using UIDocument is you can use it for both local storage and iCloud storage, so you don’t have to have two widely different code paths.

However, adding iCloud support with UIDocument does have a lot of extra steps and subtle problems to address. So I personally find it easier to get your app working locally with UIDocument, and then adding iCloud support once that’s working. So that’s what we’re going to do in this series!

5) Storage Philosophy

It is theoretically possible to design an app that has two different tabs – iCloud and local – and allow users to select where to store individual documents.

However, it appears this is not a philosphy Apple wants us to follow. According to the Document-Based App Programming Guide for iOS:

The same document also recommends that users have an option to disable iCloud for your app. I think the best place for this is in Settings, since it’s a setting that only needs to be changed rarely, reduces the clutter in your app, and discourages users from messing with it once they have it set up.

Putting it All Together

Phew – that’s a lot of background information! Don’t worry if you don’t understand everything right away, it will become more clear as we work through the tutorial.

To sum up what we discussed above, we will be doing the following for PhotoKeeper:

• Choosing a Document-Based App as our storage method.
• Creating a model class (a plain old NSObject that stores our large photo) that implements NSCoding.
• Creating a metadata class (a plain old NSObject that stores our small thumbnail) that implements NSCoding.
• Subclassing UIDocument. It will have a reference to the model and metadata classes.
• Using NSFileWrapper for input/output. Our UIDocumentClass will encode both the model and metadata into separate files inside our NSFileWrapper directory.
• Work both locally and for iCloud. We will start with local only and add iCloud support later in the series.
• Add iCloud on/off toggle in Settings. All documents will be stored either locally or in iCloud.

Note that for your apps you might make different design decisions than the above – however if you’re UIDocument based most of this tutorial will still apply, so read on :]

Getting Started

It’s finally time to code!

Create a new project in Xcode and choose the iOS\Application\Master-Detail Application tepmlate. Enter PhotoKeeper for product name, PTK as the Class Prefix, select iPhone for the Device Family, and make sure Use Storyboards and Use Automatic Reference Counting are checked (but nothing else).

Next, download the resources for this project and add them to your Xcode project. These are just two simple classes to help format a string or resize images and a few images – take a peek if you want.

Compile and run the project, and you’ll see the template has generated a skeleton of a simple master/detail app. You can tap the + button to add entries, and tap an entry to go to a detail screen.

Our goal in this first part of the series is to switch the master view to showing a list of local UIDocuments, and allow the + button to create a new UIDocument.

Before we can create a UIDocuemnt subclass though, we need to create our model classes.

Let’s start with the main model class. Create a new file with the iOS\Cocoa Touch\Objective-C class template, name it PTKData, and make it a subclass of NSObject. Then replace the contents of PTKData.h with the following:

#import <Foundation/Foundation.h>
 
@interface PTKData : NSObject <NSCoding>
 
@property (strong) UIImage * photo;
 
@end

And replace PTKData.m with the following:

#import "PTKData.h"
 
@implementation PTKData
@synthesize photo = _photo;
 
- (id)initWithPhoto:(UIImage *)photo {
    if ((self = [super init])) {
        self.photo = photo;
    }
    return self;
}
 
- (id)init {
    return [self initWithPhoto:nil];
}
 
#pragma mark NSCoding
 
#define kVersionKey @"Version"
#define kPhotoKey @"Photo"
 
- (void)encodeWithCoder:(NSCoder *)encoder {
    [encoder encodeInt:1 forKey:kVersionKey];
    NSData * photoData = UIImagePNGRepresentation(self.photo);
    [encoder encodeObject:photoData forKey:kPhotoKey];
}
 
- (id)initWithCoder:(NSCoder *)decoder {
    [decoder decodeIntForKey:kVersionKey];
    NSData * photoData = [decoder decodeObjectForKey:kPhotoKey];
    UIImage * photo = [UIImage imageWithData:photoData];
    return [self initWithPhoto:photo];
}
 
@end

As you can see, this is a very simple model class that only has one piece of data to track – the full size photo. It implements the NSCoding protocol to encode/decode to a buffer of data.

Note that it stores a version number along with the photo. This makes it easy to update the data structure if you want to in the future while still supporting older files. If you ever add a new field, you bump up the version number, then while decoding you can check the version number to see if the new field is available.

For more information on NSCoding, check out this tutorial.

Next, let’s create the metadata model class. Again, the purpose of this class is so we can store a much smaller thumbnail version of the photo that will load quickly in the master view controller.

Create a new file with the iOS\Cocoa Touch\Objective-C class template, name it PTKMetadata, and make it a subclass of NSObject. Then replace the contents of PTKMetadata.h with the following:

#import <Foundation/Foundation.h>
 
@interface PTKMetadata : NSObject <NSCoding>
 
@property (strong) UIImage * thumbnail;
 
@end

And replace PTKMetadata.m with the following:

#import "PTKMetadata.h"
 
@implementation PTKMetadata
@synthesize thumbnail = _thumbnail;
 
- (id)initWithThumbnail:(UIImage *)thumbnail {
    if ((self = [super init])) {
        self.thumbnail = thumbnail;
    }
    return self;
}
 
- (id)init {
    return [self initWithThumbnail:nil];
}
 
#pragma mark NSCoding
 
#define kVersionKey @"Version"
#define kThumbnailKey @"Thumbnail"
 
- (void)encodeWithCoder:(NSCoder *)encoder {
    [encoder encodeInt:1 forKey:kVersionKey];
    NSData * thumbnailData = UIImagePNGRepresentation(self.thumbnail);
    [encoder encodeObject:thumbnailData forKey:kThumbnailKey];
}
 
- (id)initWithCoder:(NSCoder *)decoder {
    [decoder decodeIntForKey:kVersionKey];
    NSData * thumbnailData = [decoder decodeObjectForKey:kThumbnailKey];
    UIImage * thumbnail = [UIImage imageWithData:thumbnailData];
    return [self initWithThumbnail:thumbnail];
}
 
@end

This is pretty much exactly the same as PTKData, so no need to discuss further here. We even could have used the same class, but it’s better to keep things separate in case we need more data fields in the future (which will be the case for most apps).

Congrats – now you have the model classes for PhotoKeeper!

Subclassing UIDocument

Next we are going to create a subclass of UIDocument that will combine the data and metadata into a single NSFileWrapper.

Create a new file with the iOS\Cocoa Touch\Objective-C class template, name it PTKDocument, and make it a subclass of UIDocument. Then replace the contents of PTKDocument.h with the following:

#import <UIKit/UIKit.h>
 
@class PTKData;
@class PTKMetadata;
 
#define PTK_EXTENSION @"ptk"
 
@interface PTKDocument : UIDocument
 
// Data
- (UIImage *)photo;
- (void)setPhoto:(UIImage *)photo;
 
// Metadata
@property (nonatomic, strong) PTKMetadata * metadata;
- (NSString *) description;
 
@end

Even though NSFileWrapper is basically a directory, we still need to give it a file extension so we can identify the directory as a document our app knows how to handle. We’ll use “ptk” as our file extension, so we define it here for easy access later.

Rather than letting users of PTKDocument access the PTKData directly, it’s best if you add accessors instead. This is because UIDocument is built around the concept of undo/redo – it has an undo manager and when you make changes UIDocument can auto-save in the background. Accessors are the perfect spot to register your undo actions, which you’ll see in a minute.

It’s OK if the user accesses the metadata directly though, as it’s not something the app will modify. Instead, the metadata will be automatically updated when the user sets the photo.

Next open PTKDocument.m. There’s a lot of code we’re going to add here, so let’s go over it bit by bit.

#import "PTKDocument.h"
#import "PTKData.h"
#import "PTKMetadata.h"
#import "UIImageExtras.h"
 
#define METADATA_FILENAME   @"photo.metadata"
#define DATA_FILENAME       @"photo.data"
 
@interface PTKDocument ()
@property (nonatomic, strong) PTKData * data;
@property (nonatomic, strong) NSFileWrapper * fileWrapper;
@end
 
@implementation PTKDocument 
@synthesize data = _data;
@synthesize fileWrapper = _fileWrapper;
@synthesize metadata = _metadata;

First we import the headers we need and define the filenames for the two sub-files that will be inside our directory/NSFileWrapper.

Then we create two private properties – one for the main document model class (PTKData), and one for the NSFileWrapper (the class that treats the directory as a single file). Finally we synthseize our properties.

Next add the code to write the UIDocument to disk:

- (void)encodeObject:(id<NSCoding>)object toWrappers:(NSMutableDictionary *)wrappers preferredFilename:(NSString *)preferredFilename {
    @autoreleasepool {            
        NSMutableData * data = [NSMutableData data];
        NSKeyedArchiver * archiver = [[NSKeyedArchiver alloc] initForWritingWithMutableData:data];
        [archiver encodeObject:object forKey:@"data"];
        [archiver finishEncoding];
        NSFileWrapper * wrapper = [[NSFileWrapper alloc] initRegularFileWithContents:data];
        [wrappers setObject:wrapper forKey:preferredFilename];
    }
}
 
- (id)contentsForType:(NSString *)typeName error:(NSError *__autoreleasing *)outError {
 
    if (self.metadata == nil || self.data == nil) {        
        return nil;    
    }
 
    NSMutableDictionary * wrappers = [NSMutableDictionary dictionary];
    [self encodeObject:self.metadata toWrappers:wrappers preferredFilename:METADATA_FILENAME];
    [self encodeObject:self.data toWrappers:wrappers preferredFilename:DATA_FILENAME];   
    NSFileWrapper * fileWrapper = [[NSFileWrapper alloc] initDirectoryWithFileWrappers:wrappers];
 
    return fileWrapper;
 
}

Take a look at contentsForType first. To create a directory NSFileWrapper, you call initDirectoryWithFileWrapper and pass in a dictionary that contains file NSFileWrappers as the objects, and the names of the files as the key. We use a helper method encodeObject:toWrappers:preferredFilename to create a file NSFileWrapper for the data and metadata.

The encodeObject:toWrappers:preferredFilename method will look familiar if you are have used NSCoding in the past. It uses the NSKeyedArchiver class to convert the object that implements NSCoding into a data buffer. Then it creates a file NSFileWrapper with the buffer and adds it to the dictionary.

Sweet! Now let’s implement reading. Add the following to the file next:

- (id)decodeObjectFromWrapperWithPreferredFilename:(NSString *)preferredFilename {
 
    NSFileWrapper * fileWrapper = [self.fileWrapper.fileWrappers objectForKey:preferredFilename];
    if (!fileWrapper) {
        NSLog(@"Unexpected error: Couldn't find %@ in file wrapper!", preferredFilename);
        return nil;
    }
 
    NSData * data = [fileWrapper regularFileContents];    
    NSKeyedUnarchiver * unarchiver = [[NSKeyedUnarchiver alloc] initForReadingWithData:data];
 
    return [unarchiver decodeObjectForKey:@"data"];
 
}
 
- (PTKMetadata *)metadata {    
    if (_metadata == nil) {
        if (self.fileWrapper != nil) {
            //NSLog(@"Loading metadata for %@...", self.fileURL);
            self.metadata = [self decodeObjectFromWrapperWithPreferredFilename:METADATA_FILENAME];
        } else {
            self.metadata = [[PTKMetadata alloc] init];
        }
    }    
    return _metadata;
}
 
- (PTKData *)data {    
    if (_data == nil) {
        if (self.fileWrapper != nil) {
            //NSLog(@"Loading photo for %@...", self.fileURL);
            self.data = [self decodeObjectFromWrapperWithPreferredFilename:DATA_FILENAME];
        } else {
            self.data = [[PTKData alloc] init];
        }
    }    
    return _data;
}
 
- (BOOL)loadFromContents:(id)contents ofType:(NSString *)typeName error:(NSError *__autoreleasing *)outError {
 
    self.fileWrapper = (NSFileWrapper *) contents;    
 
    // The rest will be lazy loaded...
    self.data = nil;
    self.metadata = nil;
 
    return YES;
 
}

Start at the bottom with loadFromContents:ofType:error:. Notice how all we do is squirrel the passed in contents (a directory NSFileWrapper, since that’s what we saved) into a property. We don’t actually load the data right away (although you can do that for your app if you want), since for this app we want to lazy load instead.

Lazy loading is a fancy way of saying “don’t load it until I ask for it.” This is good for our app because the master view controller only needs to load the metadata. The full data is only needed when you go to the detail view controller.

If you look at the accessors for metadata and data, they check to see if there is a directory NSFileWrapper stored, and if there is they read the appropriate file from the directory NSFileWrapper.

Finally, decodeObjectFromWrapperWithPreferredFilename does the opposite of encodeObject:toWrappers:preferredFilename. It reads the appropriate file NSFileWrapper from the directory NSFileWrapper and converts the NSData contents back to an object via the NSCoding protocol.

Almost done! Just add this to the bottom of the file:

- (NSString *) description {
    return [[self.fileURL lastPathComponent] stringByDeletingPathExtension];
}
 
#pragma mark Accessors
 
- (UIImage *)photo {
    return self.data.photo;
}
 
- (void)setPhoto:(UIImage *)photo {
 
    if ([self.data.photo isEqual:photo]) return;
 
    UIImage * oldPhoto = self.data.photo;
    self.data.photo = photo;
    self.metadata.thumbnail = [self.data.photo imageByScalingAndCroppingForSize:CGSizeMake(145, 145)];
 
    [self.undoManager setActionName:@"Image Change"];
    [self.undoManager registerUndoWithTarget:self selector:@selector(setPhoto:) object:oldPhoto];
}
 
@end

Description returns the filename without the path or extension, and photo is a simple getter.

The important part is setPhoto. Not only does this set the photo in the data, but this also creates a smaller thumbnail image and saves it in the metadata.

It also registers an undo action so that the user can undo the change (via shaking on the iPhone, or you can add a custom button). By doing this, internally UIDocument now knows that the document has been modified, so it will auto-save periodically in the background.

w00t – now you have both the data model and UIDocument working! Now it’s time to retrofit our master view controller to use it.

Creating Documents

Before we can display a list of documents, we need to have the ability to add at least one so we have something to look at. So let’s start by imiplementing creating a new document.

There are four things you need to do in order to create a new document in this app:

1. Store Entries
2. Find an Available URL
3. Create the Document
4. Make Final Changes

Let’s go over these one by one!

Storing Entries

If you look at PTKMasterViewController.m, you’ll see that viewDidLoad adds a button to the toolbar that the user can tap to create a new entry:

UIBarButtonItem *addButton = [[UIBarButtonItem alloc] initWithBarButtonSystemItem:UIBarButtonSystemItemAdd target:self action:@selector(insertNewObject:)];
self.navigationItem.rightBarButtonItem = addButton;

When the button is tapped, insertNewObject is called. The current implementation puts an NSDate in an array, which is displayed in a table view.

Instead of displaying NSDates, we want to display information about our documents. For each document, we’ll need to know its file URL, its metadata (thumbnail), the date it was last modified, and what state the document is in (more on this later).

To keep track of all of this information we need, let’s create a new class real quick. Create a new file with the iOS\Cocoa Touch\Objective-C class template, name it PTKEntry, and make it a subclass of NSObject. Then replace the contents of PTKEntry.h with the following:

#import <Foundation/Foundation.h>
 
@class PTKMetadata;
 
@interface PTKEntry : NSObject
 
@property (strong) NSURL * fileURL;
@property (strong) PTKMetadata * metadata;
@property (assign) UIDocumentState state;
@property (strong) NSFileVersion * version;
 
- (id)initWithFileURL:(NSURL *)fileURL metadata:(PTKMetadata *)metadata state:(UIDocumentState)state version:(NSFileVersion *)version;
- (NSString *) description;
 
@end

This is a very simple class that just keeps track of all of the items we just discussed.

Next switch to PTKEntry.m and add the implementation, which is simple as well:

#import "PTKEntry.h"
 
@implementation PTKEntry
 
@synthesize fileURL = _fileURL;
@synthesize metadata = _metadata;
@synthesize state = _state;
@synthesize version = _version;
 
- (id)initWithFileURL:(NSURL *)fileURL metadata:(PTKMetadata *)metadata state:(UIDocumentState)state version:(NSFileVersion *)version {
 
    if ((self = [super init])) {
        self.fileURL = fileURL;
        self.metadata = metadata;
        self.state = state;
        self.version = version;
    }
    return self;
 
}
 
- (NSString *) description {
    return [[self.fileURL lastPathComponent] stringByDeletingPathExtension];
}
 
@end

Finding an Available URL

The next step is to figure out the full URL for where we want to create the document. This isn’t as easy as it sounds, because we need to auto-generate a filename that isn’t already used. And the first step of doing that is having a way to check if a file exists.

To help solve this, let’s assume that the _objects array contains all the PTKEntries on the disk. Then all we have to do is look through this array to see if the name is already taken.

Let’s see what this looks like in code. Make the following changes to PTKMasterViewController.m:

// Add imports to top of file
#import "PTKDocument.h"
#import "NSDate+FormattedStrings.h"
#import "PTKEntry.h"
#import "PTKMetadata.h"'
 
// Add new private variables to interface
NSURL * _localRoot;
PTKDocument * _selDocument;
 
// Add new methods right after @implementation
#pragma mark Helpers
 
- (BOOL)iCloudOn {    
    return NO;
}
 
- (NSURL *)localRoot {
    if (_localRoot != nil) {
        return _localRoot;
    }
 
    NSArray * paths = [[NSFileManager defaultManager] URLsForDirectory:NSDocumentDirectory inDomains:NSUserDomainMask];
    _localRoot = [paths objectAtIndex:0];
    return _localRoot;    
}
 
- (NSURL *)getDocURL:(NSString *)filename {    
    if ([self iCloudOn]) {        
        // TODO
        return nil;
    } else {
        return [self.localRoot URLByAppendingPathComponent:filename];    
    }
}
 
- (BOOL)docNameExistsInObjects:(NSString *)docName {
    BOOL nameExists = NO;
    for (PTKEntry * entry in _objects) {
        if ([[entry.fileURL lastPathComponent] isEqualToString:docName]) {
            nameExists = YES;
            break;
        }
    }
    return nameExists;
}

Let’s start from the top. We start by adding some imports we need, and add instance variables to keep track of the local root (i.e. the Documents directory) and the selected document when a user taps a row. We also define a method to return whether iCloud is on or off. For now we set it to always off, but we’ll come back to this later.

Next we write a getter for localRoot so it can be lazy loaded. If it isn’t set yet, we use find the URL for the documents directory and squirrel it away in the instance variable.

getDocURL is a method where you pass in a filename and get the full path to the file. If iCloud is off, this simply appends the filename to the Documents directory path. We’ll add the iCloud implementation later.

Finally, docNameExistsInObjects loops through the list of PTKEntry instances in _objects and checks to see if the name matches any of them. If it does, there’s a conflict, otherwise it’s OK.

Next add this method to find a non-taken name for a file:

- (NSString*)getDocFilename:(NSString *)prefix uniqueInObjects:(BOOL)uniqueInObjects {
    NSInteger docCount = 0;
    NSString* newDocName = nil;
 
    // At this point, the document list should be up-to-date.
    BOOL done = NO;
    BOOL first = YES;
    while (!done) {
        if (first) {
            first = NO;
            newDocName = [NSString stringWithFormat:@"%@.%@",
                          prefix, PTK_EXTENSION];
        } else {
            newDocName = [NSString stringWithFormat:@"%@ %d.%@",
                          prefix, docCount, PTK_EXTENSION];
        }
 
        // Look for an existing document with the same name. If one is
        // found, increment the docCount value and try again.
        BOOL nameExists;
        if (uniqueInObjects) {
            nameExists = [self docNameExistsInObjects:newDocName]; 
        } else {
            // TODO
            return nil;
        }
        if (!nameExists) {            
            break;
        } else {
            docCount++;            
        }
 
    }
 
    return newDocName;
}

This starts with the document name passed in and checks if it is available. If not, it adds 1 to the end of the name and tries again. If that fails it keeps incrementing the number until it finds an available name.

Creating a Document

To create a PTKDocument, there are two steps:

1. Alloc/init the PTKDocument with the URL to save the file to.
2. Call saveToURL to initially create the file.

After you call saveToURL, the document is effectively “opened” and in a usable state.

After we create the document, we need to update the objects array to store the document, and display the detail view controller.

Let’s add the code! First we need to add a helper method to add (or update) a PTKEntry in the _objects array. Add the following code right before awakeFromNib:

#pragma mark Entry management methods
 
- (int)indexOfEntryWithFileURL:(NSURL *)fileURL {
    __block int retval = -1;
    [_objects enumerateObjectsUsingBlock:^(PTKEntry * entry, NSUInteger idx, BOOL *stop) {
        if ([entry.fileURL isEqual:fileURL]) {
            retval = idx;
            *stop = YES;
        }
    }];
    return retval;    
}
 
- (void)addOrUpdateEntryWithURL:(NSURL *)fileURL metadata:(PTKMetadata *)metadata state:(UIDocumentState)state version:(NSFileVersion *)version {
 
    int index = [self indexOfEntryWithFileURL:fileURL];
 
    // Not found, so add
    if (index == -1) {    
 
        PTKEntry * entry = [[PTKEntry alloc] initWithFileURL:fileURL metadata:metadata state:state version:version];
 
        [_objects addObject:entry];
        [self.tableView insertRowsAtIndexPaths:[NSArray arrayWithObject:[NSIndexPath indexPathForRow:(_objects.count - 1) inSection:0]] withRowAnimation:UITableViewRowAnimationRight];
 
    } 
 
    // Found, so edit
    else {
 
        PTKEntry * entry = [_objects objectAtIndex:index];
        entry.metadata = metadata;    
        entry.state = state;
        entry.version = version;
 
        [self.tableView reloadRowsAtIndexPaths:[NSArray arrayWithObject:[NSIndexPath indexPathForRow:index inSection:0]] withRowAnimation:UITableViewRowAnimationNone];
 
    }
 
}
 
#pragma mark View lifecycle

This is fairly simple so just take a look through, no need to discuss much here.

Next replace the implementation of insertNewObject with the following:

- (void)insertNewObject:(id)sender
{
    // Determine a unique filename to create
    NSURL * fileURL = [self getDocURL:[self getDocFilename:@"Photo" uniqueInObjects:YES]];
    NSLog(@"Want to create file at %@", fileURL);
 
    // Create new document and save to the filename
    PTKDocument * doc = [[PTKDocument alloc] initWithFileURL:fileURL];
    [doc saveToURL:fileURL forSaveOperation:UIDocumentSaveForCreating completionHandler:^(BOOL success) {
 
        if (!success) {
            NSLog(@"Failed to create file at %@", fileURL);
            return;
        } 
 
        NSLog(@"File created at %@", fileURL);        
        PTKMetadata * metadata = doc.metadata;
        NSURL * fileURL = doc.fileURL;
        UIDocumentState state = doc.documentState;
        NSFileVersion * version = [NSFileVersion currentVersionOfItemAtURL:fileURL];
 
        // Add on the main thread and perform the segue
        _selDocument = doc;
        dispatch_async(dispatch_get_main_queue(), ^{
            [self addOrUpdateEntryWithURL:fileURL metadata:metadata state:state version:version];
            [self performSegueWithIdentifier:@"showDetail" sender:self];
        });
 
    }]; 
}

We’re finally putting all of the helper methods we wrote to good use! Here we:

• Use getDocURL to find the local Documents directory
• Use getDocFilename to find an available filename in that directory
• Alloc/init a PTKDocument
• Call saveToURL to save it right away
• Keep track of the (opened) and selected document
• Add the entry to the table, and perform the showDetail segue

Note that there is no guarantee that the completionHandler passed to saveToURL executes on the main thread, hence we have to use dispatch_async to run parts of the code on the main queue which need it.

Final Changes

OK, almost ready to test this out! Just make these final changes to PTKMasterViewController.m:

// Add to end of viewDidLoad
_objects = [[NSMutableArray alloc] init];
 
// Replace tableView:cellForRowAtIndexPath with the following
- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"Cell"];
 
    PTKEntry *entry = [_objects objectAtIndex:indexPath.row];
    cell.imageView.image = entry.metadata.thumbnail;
    cell.textLabel.text = entry.description;
    cell.detailTextLabel.text = [entry.version.modificationDate mediumString];    
 
    return cell;
}
 
// Replace prepareForSegue with the following
- (void)prepareForSegue:(UIStoryboardSegue *)segue sender:(id)sender
{
    if ([[segue identifier] isEqualToString:@"showDetail"]) {
        // TODO
    } 
}

Here we just initialize the objects array and configure our table view to display information about the documents. We’ll fix up the segue and detail view controller later.

Compile and run your project, and you should now be able to tap the + button to create new documents:

If you look at the console output, you should see messages showing the full path the documents are being saved to, like this:

File created at file://localhost/Users/rwenderlich/Library/Application%20Support/
iPhone%20Simulator/5.1/Applications/
194CFF63-BE3F-4CAF-90CC-BFA843C2169B/Documents/Photo%202.ptk

However this app has a big problem. If you run the app again, nothing will show up in the list! That’s because we haven’t added the code to list documents yet, so let’s do that now.

Listing Local Documents

To list local documents, we’re going to get the URLs for all the documents in the local Documents directory, and open up each one. We’ll read the metadata out to get the thumbnail (but not the data, so things are efficient), then close it back up again and add it to the table view.

First let’s add the method that loads a document given a file URL. Add this right above the “View lifecycle” section with awakeFromNib:

#pragma mark File management methods
 
- (void)loadDocAtURL:(NSURL *)fileURL {
 
    // Open doc so we can read metadata
    PTKDocument * doc = [[PTKDocument alloc] initWithFileURL:fileURL];        
    [doc openWithCompletionHandler:^(BOOL success) {
 
        // Check status
        if (!success) {
            NSLog(@"Failed to open %@", fileURL);
            return;
        }
 
        // Preload metadata on background thread
        PTKMetadata * metadata = doc.metadata;
        NSURL * fileURL = doc.fileURL;
        UIDocumentState state = doc.documentState;
        NSFileVersion * version = [NSFileVersion currentVersionOfItemAtURL:fileURL];
        NSLog(@"Loaded File URL: %@", [doc.fileURL lastPathComponent]);
 
        // Close since we're done with it
        [doc closeWithCompletionHandler:^(BOOL success) {
 
            // Check status
            if (!success) {
                NSLog(@"Failed to close %@", fileURL);
                // Continue anyway...
            }
 
            // Add to the list of files on main thread
            dispatch_async(dispatch_get_main_queue(), ^{                
                [self addOrUpdateEntryWithURL:fileURL metadata:metadata state:state version:version];
            });
        }];             
    }];
 
}

Notice that we open the document, get what we need, and close it again rather than keeping it open permanently. This is for two reasons:

1. Avoid the overhead of keeping an entire UIDocument in memory when we just need one part
2. UIDocuments can only be opened and closed once (!) UIDocument is a “one shot” class – you can just open it once and close it once. If you want to open the same fileURL again, you have to create a new UIDocument instance.

Right after this add these methods to perform the refresh:

#pragma mark Refresh Methods
 
- (void)loadLocal {
 
    NSArray * localDocuments = [[NSFileManager defaultManager] contentsOfDirectoryAtURL:self.localRoot includingPropertiesForKeys:nil options:0 error:nil];
    NSLog(@"Found %d local files.", localDocuments.count);    
    for (int i=0; i < localDocuments.count; i++) {
 
        NSURL * fileURL = [localDocuments objectAtIndex:i];
        if ([[fileURL pathExtension] isEqualToString:PTK_EXTENSION]) {
            NSLog(@"Found local file: %@", fileURL);
            [self loadDocAtURL:fileURL];
        }        
    }
 
    self.navigationItem.rightBarButtonItem.enabled = YES;
}
 
- (void)refresh {
 
    [_objects removeAllObjects];
    [self.tableView reloadData];
 
    self.navigationItem.rightBarButtonItem.enabled = NO;
    if (![self iCloudOn]) {
        [self loadLocal];       
    }        
}

This is pretty simple file management stuff – loadLocal calls loadDocAtURL for everything in the Documents directory, and refresh kicks this all off.

The reason we enable/disable the right bar button item is you shouldn’t be able to create a new file until we have retrieved the list of files. This is because we need the list of files to guarantee a unique name when creating a new file. This doesn’t much matter now since we get the list of files right away, but is good to have in place for when that isn’t the case with iCloud.

To try this out, add the following to the bottom of viewDidLoad:

[self refresh];

Compile and run, and this time your app should correctly pick up the list of documents since last time it was run!

Where To Go From Here?

Here is a download with the state of the code sample so far.

At this point you have the data model and UIDocument wrapper working and the ability to create and list files. It might not look like much yet, but that’s the most critical part!

In the next part of the series, we’ll get this app fully functional and polished when it comes to local files. We’ll customize our table view cells, add a detail view, support deleting and renaming, and more! At that point you’ll be fully set to move to the iCloud :]

If you have any questions, comments, or suggestions about better ways to do things, please join the forum discussion below! :]

This is a blog post by site administrator Ray Wenderlich, an independent software developer and gamer.

iCloud and UIDocument: Beyond the Basics. Part 1/4 is a post from: Ray Wenderlich