CouchCocoa - An iOS client for working with CouchDB

CouchCocoa is a framework / library for iPhone use that abstracts out the work needed to talk to CouchDB instances running on the web or on the device itself. If you want to jump right into the setup for a simple project, then simply follow these steps:

1. Add CouchCocoa as a submodule to your project:
   • cd ~/dev/myProject/
   • git submodule add git://github.com/couchbaselabs/CouchCocoa.git
2. Get all the dependencies of this submodule itself:
   • cd ~/dev/myProject/CouchCocoa/
   • git submodule update --init --recursive
3. Drag & drop CouchCocoa's .xcodeproj file under your own project in Xcode
4. Add the following as your target's dependencies so that they will get built:
   • iOS Framework (CouchCocoa)
   • iOS Library (CouchCocoa)
5. Add the following in "Link Binary With Libraries" for your target:
   • libCouchCocoa.a
6. Add the following in "Header Search Paths" for your target:
   • "$(SRCROOT)/CouchCocoa/Model"
   • "$(SRCROOT)/CouchCocoa/REST"
   • "$(SRCROOT)/CouchCocoa/Couch"
   • "$(SRCROOT)/CouchCocoa/UI/iOS"
7. In Xcode, select CouchCocoa.xcodeproj in the Project Navigator and edit the Target > Build Settings and set the Skip Install setting to Yes.
8. If at a later point of time you realize that you want to work with TouchDB as well then you *may* need to update your CouchCocoa submodule and bring it up to speed:
   • cd ~/dev/myProject/CouchCocoa/
   • git checkout touchdb
   • git pull origin touchdb

If you have any problems, post your questions on the google group for mobile couchbase.

Aside from the process there are some "big picture" points to consider:

• CouchCocoa can talk directly to CouchDB (or CouchBase - a more performant variant). For example, if you use the hosting services provided by IrisCouch, you can configure CouchCocoa to work directly with that Couch server.
• CouchCocoa can work with an embedded version of CouchDB on mobile devices.
  • TouchDB is one such implementation which is lightweight and exists for iOS and Android mobile devices.
    • For iOS however, I do find it a bit confusing when I think about how to structure my project, there are two ways to do it:
      • Build and soft-link the TouchDB framework. And use CouchCocoa as a submodule as outlined earlier in the blog.
        • If you choose to use TouchDB-iOS as a submodule as well then don't forget that TouchDB's itself also needs a soft-link to CouchCocoa.framework:

          cd ~/dev/superProject
          ln -s ./DerivedData/superProject/Build/Products/Debug-ios-universal/CouchCocoa.framework ./TouchDB-iOS/Demo-iOS/Frameworks/CouchCocoa.framework

      • Syncpoint-iOS which bundles TouchDB and CouchCocoa together but lags behind the individual projects in terms of stability and features. To experiment with it, you can follow a this discussion thread where it was introduced to the community.
    • Another huge pain-point is the fact that for all of GitHub's glory it doesn't let me search for content in wiki pages so when it comes time to try out the infamous Grocery-Sync example, I'm left wondering where to look! This relative path should shed some light I hope: TouchDB-iOS/Demo-iOS/DemoAppDelegate.m
  • Couchbase Mobile is another implementation. Recently it has seen some serious progress in terms of tutorials (one & two) and example-code covering its usage.

Versioning iPhone App: Beta & Production Builds

A little bit of Google search yields the following great resources to help get started in the arena of versioning your iOS apps:

• easy-iphone-application-versioning-with-agvtool
• recipe-automatic-version-number-build-number-build-date-handling
• setting-ios-application-build-versions

In this blog entry, I'll:

• attempt to provide the grand total of everything I learned from these articles which are based in XCode3,
• provide instructions on how to do the same in XCode4, and
• explain some of the finer points which weren't clear to me without trial & error.

1. This snapshot shows how to add apple generic versioning to your XCode4 project.

2. Open YOUR_PROJECT in XCode 4 and navigate to YOUR_PROJECT > Targets > YOUR_PROJECT > Summary > iOS Application Target > Version
   
3. Even though it may seem intuitive to think so but this is NOT the version number that the iPhone app users will see.
4. Instead this is an internal build number that you can increment as many times as you like and whenever you deem appropriate. Follow the links at the top to learn more.

5. You can easily comfirm this by attempting to edit this property in YOUR_PROJECT > Target > YOUR_PROJECT > Info (maps to YOUR_PROJECT-Info.plist file) > Custom iOS Target Properties > Bundle Version
   and then confirming that the change took effect again in Summary > iOS Application Target > Version
   

6. If you Ctrl+click and ask it to Show raw keys/values

7. Then you'll notice that this maps to the key: CFBundleVersion
8. If you would eventually like to build your "About" page in the app and format a string that shows up something like version 0.1.0 (build 42), where 42 will correspond to the value of CFBundleVersion, then instead of giving it an initial value like 1.0, I would suggest setting it to 1

9. So now what corresponds to the 0.1.0 part of the version 0.1.0 (build 42) in your about page? Well, the Bundle versions string, short property with the raw key value of CFBundleShortVersionString would make up the 0.1.0 piece of that string.

10. And could this 0.1.0 be the version # that is displayed as your app's version in the App Store? Yes! this is known as the marketing version and it is what shows up to the users of the App Store.
11. What's up with the x.y.z version structure? As one of the links in the beginning explains, X - major revision number, Y - minor revision number, Z - maintenance or patch release. This is a very nice & simple concept to use.
12. Why should the starting of an App's marketing version be from 0.1.0? Because an application would like to enter the App Store as 1.0.0, so you don't want to use 1 as your major (X) version in the very beginning when you are probably in the process of distributing Ad-Hoc builds for alpha/beta testing. 1 as your minor (Y) version makes sense 0.1.0 because your app starts with the smallest set of features and then grows to perhaps 0.2.0, 0.3.0 and so on. Also the 0 as your patch (Z) version makes sense because there is nothing for you to patch at the very start. In conclusion: minor.major.patch is conveniently 0.1.0 for starters.
13. Here's what my email notification message looks like when I use TestFlightApp to publish beta builds to testers: v0.1.0 (4) of ShoppinPal is ready for a TestFlight
14. To check your CFBundleVersion via Terminal, use:

    agvtool what-version

15. All the following commands increment CFBundleVersion by 1 but do nothing to CFBundleShortVersionString:

    agvtool next-version
    agvtool next-version -all
    agvtool bump -all

16. To check your CFBundleShortVersionString via Terminal, use:

    agvtool what-marketing-version

17. To change CFBundleShortVersionString, you will yourself have to understand if the change is major, minor or patch and then use:
    

    agvtool new-marketing-version 0.2.0

18. With XCode4 there really shouldn't be any good reason not to use Git so remember to commit to the repository every time after you change the version. Perhaps even take the time to tag the repo so that you can pull the exact source for debugging if someone ever reports an issue against a specific version/build #

IBAForms: An Engaging Experience

I recently found out about IBAForms, which is an Objective-C framework for easily building forms for the iPhone. I liked it a lot so I thought I'd make it tad easier for other beginners like myself:

1. I've uploaded How To Use IBAForms Part 1 of the screencast where I cover the basics of importing IBAForms so that you may begin using it. Relying on the screencast isn't necessary as the Adding IBAForms to your project section of the README covers the same content but it may help to watch it in action.
2. Here's one of the commands used in the screencast, used in the Terminal, which you may find a little bit more helpful than pausing the screencast and trying to visually copy it from there:

   git submodule add https://github.com/ittybittydude/IBAForms.git IBAForms

3. In case you find the submodule approach less than desirable, feel free to remove it.
   
4. In How To Use IBAForms Part 2 screencast, you'll get more hands-on instructions on how to actually start adding the form fields.

When in doubt head over to the user groups for IBAForms.

Integrating with ZBar SDK 1.1

It took only 35 minutes to get a barebones scanning app up & running on the iPhone with ZBar SDK. As far as I'm concerned ZBar is a pretty good rival to RedLaser. If you haven't done already, head over to this section in the ZBar SDK docs and try out the example which will have you singing its praises in no time.

I followed it word for word other than the fact that I used UILabel instead of UITextView.

Building a step up/down notched slider for iPhone

If you implement the following delegate method with similar code then you will gain the desired effect as you move the slider with your finger on-screen.

- (IBAction) sliderValueChanged:(UISlider *)sender {
    float value = [sender value];
    if (value < 0.5) {
        value = 0;
    } else if (value > 0.5 && value <1.5) {
        value = 1;
    } else if (value > 1.5 && value <2.5) {
        value = 2;
    } else if (value > 2.5 && value <3.5) {
        value = 3;
    } else if (value > 3.5 && value <4.5) {
        value = 4;
    } else if (value > 4.5 && value <5.5) {
        value = 5;
    } else if (value > 5.5 && value <6.5) {
        value = 6;
    } else if (value > 6.5 && value <7.5) {
        value = 7;
    } else if (value > 7.5 && value <8.5) {
        value = 8;
    } else {
        value = 9;
    }
    self.slider.value = value;
}

Building IconFinder App for iPhone

After having gone through more than half of the Stanford 2010 Fall lectures on iTunes University, the urge to branch out and write something meaningful struck me. But I found myself sorely lacking on any fundamentals for getting data off the web! This is where a friend recommended RestKit and while trying to make a "real" app I also ran across IconFinder. This quickly turned around into a project where I decided to integrate with the IconFider API using RestKit to make an app that lets users explore the goodness of IconFinder as an app.

• Initial Demo # 1
• Revised Demo # 2
• Get an up to date copy of the RestKit source code:
  • git submodule add -b 67-object-mapping-2.0 git://github.com/twotoasters/RestKit.git RestKit
  • cd RestKit
  • git pull
• In order to validate the idea, I used this approach to quickly get an image to show up in the table. But surprisingly half of the images were coming over while the other half weren't, looking more closely at the JSON data I realized that the URLs with spaces in them were the ones that weren't showing up in the table so I started searching and found the right set of clues along with the solution here.
• But overall the simplistic approach for loading images synchronously is a bad idea as I read in detail here. So having made sure things looked the way I wanted them to I moved on to refine the code some more. I got lucky and found a SDWebImage library/framework that already did this in an asynchronous and efficient manner.
  • git submodule add git://github.com/rs/SDWebImage.git SDWebImage
• So far I had searched only using a static string, in order to see if I could get a nice & simple table view to be populated with an image and some text. Now, I wanted to add a search bar to make this into a meaningful icon browsing/finding app that it was supposed to be. I had read a lot about how to do this using NIB files but luckily I also found some guidance on how to add the UISearchBar programatically.
  • - (void)addSearchBar
    {
        if(!_searchBar) {
            _searchBar = [[UISearchBar alloc] initWithFrame:CGRectMake(0.0, 0.0, 320.0, 41.0)];
            _searchBar.showsCancelButton = YES;
            _searchBar.delegate = self;
            self.tableView.tableHeaderView = self.searchBar;
        }
    }
• Just because I had started out with a barebones "Window based Application" project in XCode with the intention of keeping things simple, it did not mean that I was thrilled at the idea of having to tackle all the UI work programatically now. It was time to take it up a notch.
  
  • I knew how to work programatically and I knew how to work with NIB files if I started my project with everything in-place courtesy of XCode ... BUT as is the case with many beginners, these were two mutually exclusive approaches in my mind and it is difficult to make a mental leap where the two are one & the same. With a little help and a bit of experimentation I got over that hump. I'll try to post a quick screencast to show it in action.
• Now it was time to make the search a bit more specific by allowing the users to search for the icons based on size that could be controlled by a slider to jump between ranges like 16x16px, 48x48px, 512x512px etc. Once again I had some help from the web and ended up developing my own simple scheme.
  

RestKit - Getting Started w/ examples on iPhone

The lectures provided by Stanford University on iTunes offer a great start for anyone looking to kick-off iPhone development. Yet they leave a gap when it comes to driving the UI with an easy to use WebServices library. And the thought of "rolling your own" can be scary. This is where RestKit fills in the gap by providing an Objective-C framework that makes it easy to send/receive JSON messages and much much more...

If you want to quickly get some hands-on time with an iPhone simulator and all the features that RestKit has to offer then have a quick peek here.

Lightning fast iPhone mockups with LucidChart

With any kind of design work the very first challenge is picking the right tool for the job. After evaluating many tools that were listed as Top 10 in most people's lists, there was only one that really met (nay exceeded) all the requirements for usability, slickness, polish & collaboration ... when given the skill level of a complete newbie ... and that tool is LucidChart.

Without further ramblings, here's a video glorifying the beauty of working with Lucidchart ... all in under five minutes.