iPhone Programming Tutorials » SQLite

Simple Sqlite Database Interaction Using FMDB

brandontreb — Fri, 04 Nov 2011 19:52:19 +0000

Introduction

In the age where Core Data is king, the database that started it all is often overlooked. I’m talking of course about sqlite. As you may or may not know, prior to core data, sqlite was the preferred method of storing relational data on iOS devices.

Although, most developers don’t interact with sqlite directly, they still use it under the hood as the primary data store for core data. This is great and all, but there are often times when raw sqlite is still the preferred storage method.

A few of these might include:

Caching
Preferences
Simple objects
Portability
Cross platform applications

Recently, I have had to make heave use of raw sqlite as a caching strategy in a new project that I’m working on. Being that we are developing a framework for other developers to include in their projects, we can’t always assume that they have their environment set up to use core data. When I was but a n00b iOS developer I did all of the crazy sqlite management by hand. See This post series, but don’t spend too much time there because it’s embarrassing.

Gross right? Now, there is a much easier way to manage and interact with your sqlite databases. This library has been around for quite some time and I wish I had known about it earyly on.

FMDB

FMDB stands for Flying Meat Database. What a great name… This project aims to be a fully featured wrapper for sqlite.

You can clone their repository on their github.

This tutorial will give you a brief introduction to using FMDB to create a database, create a table, insert, fetch, and delete data.

Project Set Up

The first step is to download/clone fmdb from the url above. Once downloaded drag everything inside of the src folder into your project except fmdb.m. That file contains unit tests and a main, which will cause some conflicts in your project.

The next step is to link in the sqlite library. To do this:

Click your project in the left column of XCode
Click the main target in the middle column. In our case it’s “FMDBTest”
Click the “Build Phases” tab in the third column
Expand the arrow next to “Link Binary With Libraries”
Click the “+” button
Search for libsqlite3.0.dylib and double click it

When you are all done, it should look like this:

Now, that we have the library in place, let’s write some code.

Creating A Database

Obviously where you create your database is up to you, but we are going to do it in the appDelegate.

In addition to working with existing databases, fmdb can easily create any number of databases for you on the fly. After importing FMDatabase.h in our AppDelegate.m file, we can add the following code to the application:didFinishLaunching method.

NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
NSString *docsPath = [paths objectAtIndex:0];
NSString *path = [docsPath stringByAppendingPathComponent:@"database.sqlite"];
 
FMDatabase *database = [FMDatabase databaseWithPath:path];

First, we resolve the path to the documents directory. Be careful, if you don’t need your database to be backed up, use the cache directory instead. When you send a path to the databaseWithPath method of fmdb, it first checks if the database exists, and if not, it creates it. Similarly, we could copy an existing database to the documents directory and source it the exact same way.

Opening The Database And Creating Tables

In order to perform any action on the database, it must first be opened. Here is the code to open the database and create a users table. Don’t worry about closing it right now, we will do that when we are all done.

[database open];
[database executeUpdate:@"create table user(name text primary key, age int)"];

Here we first call the open method of the database to open it. Next, we use the executeUpdate method to create the table. Make sure you use this method and not executeQuery when creating a table. This is a common error. The database should look like this after our update:

After we are all done here we close the database.

Inserting And Deleting Data

Inserting data using sqlite is very straight forward. You can either build your strings and pass them in directly OR use the sqlite format using “?’s” and letting fmdb do the work. Below is an example of each:

// Building the string ourself
NSString *query = [NSString stringWithFormat:@"insert into user values ('%@', %d)",
@"brandontreb", 25];
[database executeUpdate:query];
 
// Let fmdb do the work
[database executeUpdate:@"insert into user(name, age) values(?,?)",
@"cruffenach",[NSNumber numberWithInt:25],nil];

Generally, the second route is preferred as fmdb will do some of the sanitizing for your (such as add slashes to single quotes).

Now that we have some data in our database, let’s delete it. The following code will delete all users with an age of 25:

[database executeUpdate:@"delete from user where age = 25"];

And that should remove both of the records that we inserted.

Querying The Database

Querying the database is a bit more tricky than inserting and deleting. FMDB has some great utility methods for helping us out in certain circumstances, but for this tutorial, we will assume the don’t exist and show you how to fetch data out. If you are following along in a sample application, put this code before your delete code (so that we actually have some data to work with).

Below is an example of fetching all users from the database:

FMResultSet *results = [database executeQuery:@"select * from user"];
while([results next]) {
    NSString *name = [results stringForColumn:@"name"];
    NSInteger age  = [results intForColumn:@"age"];        
    NSLog(@"User: %@ - %d",name, age);
}
[database close];

We first query the database using the executeQuery method. This returns to us an FMResultsSet. Next we start a while loop that continues while there are results to be retrieved and fetch out each of our data points. Finally, we just print out each user.

And finally, our database gets close…

Conclusion

This concludes our sqlite using fmdb tutorial. As always, if you have any questions, please leave them here or write me on twitter.

You can download the source for this tutorial here

Happy iCoding!

How To Integrate Google Analytics Tracking Into Your Apps In 7 Minutes

brandontreb — Thu, 22 Apr 2010 15:02:06 +0000

Ok, maybe that title is +- 3 minutes depending on how efficient you are ;).

What?

So, why would you want to integrate Google Analytics into your iPhone application. Duh, for the same reasons you would integrate it into your site. Google has extended their killer analytics platform to include mobile devices including the iPhone and Android devices.

The analytics API gives you some very powerful options to get as nitty gritty as you would like in your application tracking.

Why?

Uhh, because stats are freakin sweet. Even if you don’t have a million+ downloads of your app, it is still interesting to know how your users are using your application. Being able to track every single action made by a user is priceless when thinking about the direction of your app including what features to add, improve, or scrap.

Imaging spending all of your time on some complex feature to find out that only 1% of your users even care about that feature. How could you know that only 1% of your users actually care about that feature unless you are doing some sort of tracking.

So before you add that super duper all in one end all be all 1337 feature to your app, consider reading the rest of this tutorial and add stat tracking first. It is quick and painless and I promise that it will be totally worth it.

Configuring your Google Analytics Account

Google Analytics is a free server provided by Google. If you dont already have an account, you can sign up for one with your existing Gmail account. http://google.com/analytics. Sign up and log in.

The first thing you will want to do is Add a new Website Profile.

On the next page:

Select Add a Profile for a new domain
Enter in some URL – This doesn’t really matter since google doesn’t use it to identify your app. A good convention is iphone.yoursite.com or appname.yoursite.com so that you know these stats are for your iPhone app.
Select your country and timezone
Click Finish

Pretty simple… On the next screen, make sure you copy the Web Property ID. This number (begins with UA) is what we will be using to uniquely identify your application.

That’s all for the web side of things! Now on to the iPhone part.

Download the Google Analytics Library and Add It To Your Application

This could not be easier. Head on Over to http://code.google.com/apis/analytics/docs/tracking/mobileAppsTracking.html . They explain much of the steps so you could read the rest there, but I will lay them out in detail here with screesnhots. Download the Analytics SDK for iPhone and extract it.

There are 2 files that are important. Drag both files from the Library folder into your XCode project. These files are GANTracker.h and libGoogleAnalytics.a.

When XCode pops up the confirmation box, make sure that you check the box that says “Copy items into destination group’s folder (if needed)”. This will ensure that the code gets place in your project directory.

Include CFNetwork and Link Against the sqlite framework

The google analytics framework requires the use of CFNetwork (for interent connection detection) and the sqlite framework (most likely to store events when the user does not have internet).

Let’s start by adding CFNetwork to the project. Right click on the frameworks folder and select Add -> Existing Frameworks. Next, select CFNetwork.framework from the list and click Add.

Now we need to link the project against libsqlite3.0.dylib. To do this Click Project -> Edit Active Target “” where is the name of your XCode project.

Next, click the + button at the bottom to bring up the library picker. Select libsqlite3.0.dylib and click Add

Including and Initializing the Tracker

Since the Analytics tracker is a singleton class, we only have to initialize it once and the rest of the application can use the same instance.

Let’s start by opening up the app delegate and adding the code to import the Google Analytics framework.

#import "GANTracker.h"

Now you need to initialize the tracker… Make sure you have the UA number handy that you received from Google earlier. Add the following code to you applicationDidFinishLaunching method.

[[GANTracker sharedTracker] startTrackerWithAccountID:@"UA-15609865-3"
				dispatchPeriod:10
				delegate:nil];

Make sure you replace my UA number with yours. The dispatchPeriod variable tells the tracker how often to report back to Google. Google suggests using 10 seconds in their example so we’ll stick to that.

Tracking Pageviews and Custom Events

Google gives you 2 different ways to track how your users use the application. The first way is via pageviews. Pageviews work just like they do in the browser as if the user navigated to a new page in your website. Some examples of when to use pageview are when you have a tab interface or a flipside view controller. I would not suggest using a pageview every time the user performs an action such as click a button.

The second way is via custom events. These are really cool. With custom events, you can easily see HOW your users are using your application. Examples of events are button clicks, typing in a textbox, submitting high scores, etc…

We will see an example of implementing each of these methods and take a look at how they appear inside of the Google Analytics website.

Pageview method

Here is an example of a pageview when the user first launches the app. Put this code inside of your applicationDidFinishLaunching method.

NSError *error;
if (![[GANTracker sharedTracker] trackPageview:@"/app_launched"
                                        withError:&amp;error]) {
     // Handle error here
   }

Note that the “app_launched” is essentially our page name similar to index.html or aboutus.php. You can add this code anywhere in you app that you want to add a page view. Make sure you include the GANTrack.h file and change the pagename for each new location.

Event method
Here is an example of an event that gets fired when the user presses a Save button.

- (IBAction) saveTheWorld:(id) sender
{
	NSError *error;
	if (![[GANTracker sharedTracker] trackEvent:@"button_click"
				             action:@"save_the_world"
					      label:@"my_label"
					      value:-1
					  withError:&amp;error]) {
		// Handle error here
	}
}

What’s really cool about event tracking is you have 3 levels of customization. You have the category, the action, and the label. How you organize it is up to you, but make sure the grouping makes sense. In the example above, I will use the category “button_click” every time a user clicks any button. The action will determine which button was clicked (in this case, it’s “save_the_world”). Finally, the label is just another level. I’d suggest using the UDID of the users device.

Now that we have implemented our code, let’s take a look inside of our Google Analytics account and see what the stats look like.

This is just some of our sample data from another app. Notice the interface is exactly the same as it is when you are tracking website statistics. It shows you unique visits as well as pageviews. You get all of the advanced reporting too including time spent on each “page”.

Now we take a look at events. To find the actions click Content -> Event Tracking inside of your Google Analytics Page.

In the above screenshot, we see tracking for an event called “clap”. It shows us the number of times the users “clapped” within a given day.

Conclusion

One last thing I want to mention before concluding this tutorial. Google Analytics stats are 1 day behind. What this means is, you won’t see your stats appear immediately. So, before you comment here because you don’t see the stats appearing, please please please wait one day and check your stats again. That is all

Be one of the cool kids, follow me on Twitter.

Happy iCoding

iPhone Programming Tutorial – Creating a ToDo List Using SQLite Part 4

brandontreb — Mon, 22 Sep 2008 23:47:39 +0000

This is the final installment of our 4 part series of creating a Todo list for the iPhone. In this tutorial, I will detail how to add and delete new todo objects from the SQLite database. Make sure that you have completed the following tutorials before you begin this one:

When you have completed this tutorial, you should have a main screen that looks something like this:

Let’s get started…

The first thing we need to do is add the UIBarButtonItem items to the NavigationBar so that we get the “Edit” and “Add” button. Open up RootViewController.m and add the following code to the viewDidLoad method.

The first thing we see is the line that sets the leftBarButtonItem to self.editButtonItem. This automatically adds the “Edit” button to the NavigationController. Also, it sets up the functionality that allows the “delete” buttons to be displayed when the button is pressed. You can see this functionality if you do a “Build and Go” at this step. Next, I have manually created a UIBarButtonItem and added it to the navigationbar. This can be done in Interface Builder, but I wanted to show you how to do it manually and assign an action to it (I’m sure you will require this functionality in a future program). Here is a break down of the parameters:

initWithTitle – The text to be displayed on the button
style – How the button will look
target – The class object that handles the messages sent from this button
action – The method to be called when the button is passed. We can use @selector and give it the name of the function to call.

Finally, we assign this button to the rightBarButtonItem. If you do a Build and Go, it should error since we haven’t created the addTodo method. We will do that in a bit. Now, let’s create a method inside of our Todo object that will add new Todos to the database.

Open up Todo.h and add the following code:

So in addition to the insertNewTodoIntoDatabase method, we also see the deleteFromDatabase method signature. I have just added this so I don’t have to come back to it later. We will be implementing this when I show you how to delete todos from the database. One thing to note about the insertNewTodoIntoDatabase method is it has a “+” rather than a “-” sign. This means that it is a static method. Static methods are associated with the class not the instance meaning we can call this method without instanciating this class. So we can do stuff like Todo.insertNewTodoIntoDatabase. Now we will implement this method.

Before we can do this, we must declare a few more static sqlite3_statement’s. Add the following statements to the top of Todo.m

Nothing new here…Now implement the following method:

This is similar to our update method. Notice that we are inserting default values into the database. This is so we don’t run into any problems with null or nil values. The most important part of this method is the fact that it returns the primary key of the newly created todo object. This will be used later so we can immediately transition to the todo when the “Add” button is pressed. The last thing we need to do to the todo object is update the dehydrate method so that the todoText gets saved if it gets changed. Update the dehydrate method to look like this:

There are only a few minor changes here. First we see the “text = ?” part added to the sql statement. This is simply so we can update the text of the todo. The other change is we bound the self.text property to the 1st question mark in the sql statement. One thing to notice is we call [self.text UTF8String]. This is because sqlite3_bind_text takes a (char *). This will convert an NSString to an acceptable format.

Now we need to add a method inside of our RootViewController to add a todo. This is the method that will be called when the user presses the “Add” button. Inside of RootViewController.m add the following code:

First, we get a reference to the appDelegate object. This is because we need to call its addTodo method. Next, we instantiate the TodoViewController if it has not already been instantiated. We need this around because we will push it on to the view stack and transition to it after we create our new todo object. After this is done, we call the addTodo method of the appDelegate. It will return the newly created todo object and the view will be transitioned to its detail screen in order to update its details. Now we need to implement the method addTodo inside of our appDelegate. Open up todoAppDelegate.h and add the following code to create the method signature.

Now, let’s implement this method. Open up todoAppDelegate.m and add the following code:

First, we are calling the insertNewTodoIntoDatabase method of the Todo object. Notice that we are simply calling the method without first building an instance of a todo object. As I said in tutorial 3, this is because that method is static and gets called without building an instance of the class. Next, we insatiate the todo object that was just created by calling its initWithPrimaryKey method. This will give us reference to the new todo object. Finally, we append this todo to the end of our todos array. Since our UITableView is updated with this array, it will automatically include the new todo object. The last line just returns this todo object.

Remember is the last tutorial we made it so the users could update the status and the priority of a todo? Well, now we also need to give them the ability to update the text of the todo. So open up TodoViewController.h and add the following code:

Ok, so I’m guessing you are wondering why the UITextView for the todoText object has been changed to a UITextField. Well, I will tell you. UITextView doesn’t have the methods that we need to save the text with our current design. We will also be changing this on our Interface inside of Interface Builder. So for now, just believe me and anywhere it says UITextView, change it to UITextField. The only additional code we added here is the method signature for the updateText method. It’s an IBAction that will get called when the user presses the “Done” button on the keyboard after setting the text for the todo. Next, we need to implement this method. Open up TodoViewController.m and add the following code:

All this does is update the text of the todo to the text that the user entered inside of the UITextField. The last thing we need to do in order to add a todo is to replace the UITextView with a UITextField and connect it to our updateText method. Double click on your TodoViewController.xib file to open it in Interface Builder.

Now click on the UITextView on your interface and press the delete key on your keyboard to delete it. Now, drag a UITextField from the library and drop it onto your interface. Resize it to fit. When you have completed that, your interface should look something like this:

Now we need to connect this component. Make sure it is selected and click Tools -> Connections Inspector to open up the connections inspector. Drag from the circle next to the method “Did End On Exit” to the “File’s Owner” object. The words udpateText should pop up. Click on them to make the connection. Next, click in the circle next to “New Referencing Outlet” and drag it to the “File’s Owner” object. Select todoText when it pops up. The Connections Inspector should look like this:

Now we are done with Interface Builder. Go ahead and close it. We are now able to add todos. The last thing we need to do is give the ability to delete todos from the list as well as our database. This is all done in code, and we won’t need interface builder for this.

Let’s start by adding the methods to the appDelegate to handle the deletion of todos. Open up todoAppDelegate.h and add the following code:

All we see here is a signature for the removeTodo method. Also, be sure to add a #import “Todo.h” statement to the top of this file so that we can interface with the todo objects. Now let’s implement the removeTodo method. Open up todoAppDelegate.m and add the following code:

The first line looks up the todo in the todos NSArray. It returns the index in the array of the todo to be deleted. Then, we call the deleteFromDatabase method on the todo object and then remove it from the todos array. Since the UITableView is updated via this array, it will automatically remove the todo without any additional code on our part.

Now, let’s create the removeTodo method for the todo object. We have already written the method signature in Todo.h in a previous step, so open up Todo.m and add the following code:

Remember the delete_statement variable is a static sqlite3_stmt that we declared in a previous step. First, we check to see if it is nil. If it is we compile the statement using the sqlite3_prepare statement. Next, we bind the primary key of the current todo to the “?” in the sqlite3 statement. Next, we just step the statement to execute it and reset it. The last thing we need to do to delete todos from the database is to specify what happens when the user presses the “delete” button. Open up RootViewController.m and add the following code:

The first step (like the first step of many functions) is to get a reference to the appDelegate. Next, we check to see if we are currently editing. If so, call the removeTodo method on appDelegate. The next line, removes the row from the UITableView at the given indexPath.

Now click Build and Go! You should now be able to add and delete todo items from the database. This concludes our four part series of creating a todo list for the iPhone. As always, if you have any questions feel free to leave them in the comments section. If you get lost at any time you can download the sample code here.

Happy iCoding!

iPhone Programming Tutorial – Creating a ToDo List Using SQLite Part 3

brandontreb — Thu, 11 Sep 2008 01:39:29 +0000

This is part 3 in our multipart series of creating a todo list for the iPhone. For this, you must have completed the following tutorials.

The focus of this tutorial will mainly be on viewing the todo items when selected. I will also show you how to update the todo status. This will require us to use interface builder. When you are completed, you will be able to edit todos through an interface similar to this:

Bringing Your Code Up To Speed

For this tutorial, we will need to get the last variable from the todo database. This is of course being the status variable. If you recall, it’s a boolean value (1 for complete, 0 for in progress). We need to get it from the database and associate it with the todo object. First let’s create a property to hold this value. Open todo.h and add the following code:

So a few changes here…First there is the added NSInteger status. This will be the property we associate with the status (complete or not) of the todo. We also create a property from it. Next, there is a BOOL property called “dirty”. We will use this object to signify when a todo has been altered. You will see how this comes into play when we implement the dehydrate method. Also, I have added 3 method signatures. updateStatus will be the method called when we want to update our status variable. Similarly, the updatePriority method will be called to update the priority. Finally, we have added a dehydrate method. This method should be familiar (or confusing) if you have messed with Apple’s books example. Basically, it will be used to save the state of the todo to the database. We will be calling this method on each todo item when the program exits. I will show you how to do this in a little bit.

Be sure to add the status variable to the synthesize line. Also, as we did before, we need to create a static sqlite3_stmt to hold the compiled dehydration statement. Add the following code to Todo.m:

Now let’s implement the methods. Add the following code:

The first two methods (udpateStatus and updatePriority) are pretty strait forward. They update the status and the priority of the todo and then set the “dirty” property to 1. This signifies that the todo has been altered and will need to be saved to the database.

Finally, there is the dehydrate method… We will call this method on each todo upon termination of the program. If the todo is “dirty” meaning the dirty property was set to YES, we will need to save the new data to the database. The database code should look pretty similar to code in previous tutorials. First, we check to see if the dehydrate_statement is equal to nil. If you recall, this will only happen the first time this method gets called. Next we create the update statement and then bind our variables to each of the “?”‘s. Notice the ordering. The numbers represent the question marks from left to right (1 being the first, 2 being the second, 3 being the third). It took me quite some time to figure this out. Finally, we execute the sqlite statement by calling sqlite3_step and then reset the statement.

The last thing we need to do to Todo.m is change the SELECT statement in the initWithPrimaryKey method to grab the ‘complete’ field. Update the code to look like the screenshot below:

There are not really many changes. The first change is the added status to the synthesize line. Next, the sql statement was updated to read

SELECT text,priority,complete FROM todo WHERE pk=?

This allows us to get the “complete” field from the database. Finally, there is the line “self.status = sqlite3_column_in(init_statement,2);”. This is assigning the status property to the data at index 2 in the sql data array. We can now use this field.

One thing we need to do for the navigation to function properly is add a title to our main view. Open up rootViewController.m and add the following code to the viewDidLoad method:

Create the Todo Detail View

Now we are going to create the view that will display when the user selects the todo in the UITableView. Go ahead and open up Interface Builder by selecting one of you existing nib (.xib) files. Once it’s open add a new View by clicking File -> New and select View. Drag the following controls.

UITextView
UISegmentedControl – For this you will need to set the number of segments to 3. You will also see a dropdown menu below this option. Select each segment and fill in one of the priorities for the title. Here is a screenshot. You should give a title to each (Low , Medium, High).
UILabel – This will be used to display the status
UIButton – Users will click this button to update the status (Mark as complete)

When you are done, your interface should look something like this (but probably better):

I know that my interface doesn’t look the coolest. I’m a programmer not a graphic designer… Ok save this view by pressing Command-S. Make sure you are in your current projects directory. Name it TodoViewController and press Save.

It will then ask you if you want to add it to your project. Check the box next to the word todo and click Add.

Now close Interface Builder. Next, we are going to add the viewController class and set up variables to interface with this view.

Create TodoViewController Class Files

Click File -> New File… Select UIViewController Subclass and click Next.

Name the file TodoViewController and make sure that the box that says “Also create TodoViewController.h” is checked and click Finish.

Open up TodoViewController.h and add the following code.

Basically, we are setting up Interface Builder Outlets for each of the UI components to be connected to. Notice, the UIButton has an IBOutlet. This is because we will need to update the text on the button depending on whether or not the todo is completed. Also, I have an IBAction called updateStatus. We will be connecting this to the button we created. It will toggle the status (pending/complete) of a todo item. Finally, we see the updatePriority method. This method will be called when the user selects one of the priority segments in the UISegmentedControl. Next, open up TodoViewController.m and add the following synthesize code:

This will allow us to get and set these variables.

Before we connect this code to the Interface, we need to implement the methods that will be called when the user presses the button to mark a todo as complete as well as when the user presses a segment in the UISegmentedControl. Inside of TodoViewController add the following methods.

Let’s go through this. First we see the updateStatus method. This gets called when a user presses the button to alter the status. We basically check the current status of the todo (whether or not it’s completed) and depending on that, change the text to be displayed on the UIButton. So, if the todo is not complete (in progress) and this button is pressed, the text will be changed from “Mark As Complete” to “Mark As In Progress”. Finally, we call the updateStatus of the todo and pass the new value (1 or 0) to it.

Next we see the updatePriority method. It simply reads the value of the UISegmentedControl by calling the selectedSegmentIndex method on it. The next part looks a little messy. There are 2 reasons that reason we can’t just pass the value of the UISegmentedControl directly to the method. The first is, the UISegmentedControl is ordered in acending order (1, 2, 3…), but our priorities are in descending order (3 = low, 2 = medium, 1 = high). This is where the “2 – priority” comes from. Next, UISegmented controls are “0 indexed” meaning the indices start at 0 and increment from there. So we need to add a “+1″ to the index as our todo priorities start at 1.

Now we need to connect the UI Components in Interface Builder to this code. Double click on TodoViewController.xib to open it in Interface Builder.

Connecting UI Components To Code

We first need to associate this view with the class we just created. In the Interface Builder, click on the File’s Owner object. Next click Tools -> Identity Inspector. You should see a drop-down next to class. Select TodoViewController from this list and you will see the variables we just created appear in the boxes below.

This is what the Identity window should look like after you have selected TodoViewController.

Now that the class is associated, we can begin connecting the components. We will start by connecting the view. Click on the top of your view window to select the view itself (make sure you haven’t selected any of the UI components). Click Tools -> Connections Inspector. Next to where is says “New Referencing Outlet” click in the circle and drag it to the “File’s Owner” object and release it. The word “view” should pop up. Click on the word view. It should now look like this.

Now repeat these steps for each of the components (UITextView, UISegmentedControl, UILabel, UIButton) connecting each to the “File’s Owner Object”. Instead of the word “view” popping up, you should see the variable name for the corresponding variable that you want to connect the component to. So for the UITextView, you should see the word “todoText” appear when you drag it to the File’s Owner object.

We need to connect the UIButton to the updateStatus method we created. To do this click inside the “Touch up inside” circle and drag it to the “File’s Owner” object. You should see the text “updateStatus” appear. Click on it. If all goes well it should look like this.

The last thing we need to do inside of Interface Builder is connect the UISegmentedControl. Click on it in your view and then click Tools -> Connections Inspector… Click on the circle next to the “Value Changed” method and drag it to the “File’s Owner” object. You will see the method updatePriority popup. Go ahead and click on it. Your window for the UISegmentedControl should now look like this:

Now, let’s display this view when a row is selected. Close Interface Builder and open up RootViewController.h and add the following code:

We need a variable to associate with the TodoViewController that we will be transitioning to. Next, open up RootViewController.m and add the following code to synthesize this property.

Keeping the UITableView Up To Date

Whenever a todo item is altered (status or priority) the UITableView needs to be updated with the new changes. Add the following code to the viewWillAppear.

The line [self.tableView reloadData] reloads the table data every time the view appears (or reappears). This will ensure that our table is always up to date.

Now add the following code to the didSelectRowAtIndex method:

This is quite a bulky method with a lot of familiar code. First, we get a handle to the appDelegate and the todo object that was selected. Next, we push the todoView (the view you created in interface builder) on to the viewController stack to transition to it. After that, we are setting some of the properties of the view. The title is set to the text of the todo (it will get truncated if it is too long) and the UITextView is also set to the todo text. Next, we are translating our priority to an index for the UISegmentedView. I explained why this was necessary above. Then the index of the UISegmentedControl is set by using the setSelectedSegmentIndex method. Finally, we set the text of the button and label based on the status of the todo.

The very last thing we need to do is tell the application to save itself when it closes. Open up todoAppDelegate.m and add the following code to the applicationWillTerminate method:

If you ask me, this is some freakin sweet functionality. The method “makeObjectsPerformSelector” is a built in method on an NSArray. It basically loops over every object in the array, calling the method you pass in to it on each one. It’s like doing a for loop and calling the todo[x].dehydrate method for each todo. Only this is much cleaner. So, to reiterate, this method will call the dehydrate method on each todo. If the todo is “dirty” meaning it was altered, it will be saved to the database, otherwise the dehydrate method will do nothing.

* One thing to note. The applicationWillTerminate method will not be called if you quit the simulator while the application is running. To make sure it gets called (and the todo data gets saved) make sure you press the home button on the simulator after you make alterations to the todos. If you simply press Apple-q and quit the simulator while inside of the todo program, no data will be saved and you will post angry comments on my site telling me that my tutorial is wrong.

Click Build and Go and just sit back and enjoy the magic of rock! I mean XCode…

When you select a todo item, your screen should look something like this:

Well, that concludes part 3 of our series. Join me next time, when I will show you how to add and delete todos from the SQLite database. If you have any comments or questions, feel free to leave them in the comments section. I would love to hear them. Please subscribe to the RSS feed if you want to be automatically notified of new tutorials. If you get lost at any point, you can download the sample code for this tutorial here.

Happy iCoding!

iPhone Programming Tutorial – Creating a ToDo List Using SQLite Part 2

brandontreb — Tue, 02 Sep 2008 17:35:46 +0000

This tutorial is part 2 in our series of creating a to-do list. I will assume that you have completed the following tutorial and its prequisites.

iPhone Programming Tutorial – Creating a ToDo List Using SQLite Part 1

I will be using the code produced from that tutorial as a base for this one. When you are finished with this tutorial, your application will look something like this:

In this section, I will not only teach you how to display the SQL data in UITablewView, but I will be detailing how to display it in multiple columns with images and text. For this tutorial, you will need to download the following images.

We will be using these images to denote the priority (Green = low, Yellow = medium, Red = high).

Bring Your Code Up To Speed

Before we begin, we need to add some code to the Todo.h and Todo.m class to support the priority field in the database. Open up Todo.h and add the following code:

All that is new here is the added NSInteger priority property. We will be using this to get and set the priority for a given todo object. Next, open Todo.m and add the following code.

The first line that has changed is the synthesize line. We added our priority property to allow XCode to create the getter and setter methods for it. Next, you will notice that the sql statement has changed slightly. We are now getting the priority in addition to the text from the todo table. Finally, we set self.priority property to the selected priority value from the todo table. This is done by using the sqlite3_column_int method. We pass the init_statement and the number 1. 1 being the index of the sql array for which the priority data is contained.

Add Images to Your Project

Download the images above and save them to your project directory. Inside of your project, right click (control-click) on the Resources folder and click Add -> Existing Files… Browser for the images, select all of them and click Add. Check the box that sais “Copy items into destination group’s folder (if needed)”. Click Add. The image files should now appear inside of your Resources folder.

Create a UITableViewCell Subclass

To display data in columns within a UITableView, we have to create our own cell class that defines the type of data we want to display. By default, Apple provides us with a simple cell object that can only display one column of text. Normally, this is fine as it will work for a wide variety of applications. Since we require 3 columns for this tutorial, we need to wrap our own cell object.

Click File -> New File… and select UITableViewCell. Click Next.

Name this file TodoCell and make sure this that the box that sais “Also create TodoCell.h” is checked.

This will create a “barebones” UITableViewCell object with some basic methods already filled out. Let’s add some properties to this class. Open up TodoCell.h and add the following code.

Let’s take this line by line…

First, we see a Todo object being declared. Each cell will know which Todo item is associated with it. This will help out when updating the data in each cell. Next, we see 2 UILabels and a UIImageView. To understand why these components are needed, here is a screenshot of how each cell will look.

We see the “Green Dot” which is an image being rendered by a UIImageView. The word “low” and “Take out the trash” are both UILabels. After they are declared, we simply create them as properties. Notice that we are NOT creating a property for the Todo object. We will not be synthesizing it either. This is because we want this variable to be private. Setting this variable requires some additional code so we don’t want any code writer to simply be able to say cell.todo = foo; You will see why this is so further on in this tutorial.

Below this are some method declarations. First we see the method “imageForPriority”. We will be using this method to decide which image (green, red, yellow) gets displayed for a given priority. Next, we see the “getter and setter” methods for the todo object. As I explained above, the setter will contain additonal code besides assigning the todo object.

Now open up TodoCell.m. We will be writing quite a bit of code in here so I will break it up the best I can. First, add the following code to create some of the initialization:

Ok, some new stuff here. First, we see 3 static UIImages. These will hold reference to each of the three images (red, green, yellow). Since we only need to allocate them once, we make them static. Static means that they will be associated with the class not the instance. So we can make as many TodoCells as we want but only 3 UIImages will be created. On the next line there is a private interface. This allows us to declare a private method that no one else can use except this class. Following this is the synthesize line. Notice again that we are NOT synthesizing the todo object.

Looking at the initialize method… All that is going on here is we are intanciating each of our UIImages with the correct image for a given priority. This initialize method will get called once when the first instance of the todocell class is built. Moving on… Add the following code: (Note: it might be small and hard to read. If this is the case, click on the image to open it and the text will be full size)

This is the initialiazation method for any UITableViewCell. First, we need to call the super classe’s (UITableViewCell) initWithFrame to ensure that the underlying components of the cell get set up properly. Next, we get a reference to the contentView. The contentView is the view for each cell. We will be adding all of our UI components to this view.

The next 3 lines initialize a UIImageView and add it to our view. Notice that we are populating it with the priority1Image. This will just be a dummy placeholder until we update it.

Following this, we initialize the todoTextLabel. This label will display what it is we need “to do” such as “Take out the trash”. There is a method that we will be calling called “newLabelWithPrimaryColor”. This is a method I will detail a little further down. What it will do is build a new label with the attributes that we specify when we call it. This method was taken directly from Apple’s “Seismic XML” sample code. It’s pretty handy. After this gets called, we simply add the new label to our view and these steps get repeated for the todoPriorityLabel.

Finally, the method “bringSubviewToFront” is called on the priority UIImageView. This method is used in case there is text that gets near the image. It will cause the image to appear above the text. You can use this for layering your UI components.

Still with me? Good… now let’s add the following “getter” and “setter” methods for the todo object.

The first method todo is simple. All it does is return our todo object. The setTodo is a little more involved…

First, we set the incoming (newTodo) to our classe’s todo object. Next, we update the UITextLabel so we can display the detailed todo information. Following this we set the image of our UIImageView by calling the method imageforPriority. I will detail this method further down in this tutorial but all it does is return an image for a given priority. Last, we have a switch statement. The syntax of a switch statement is the same in objective C as it is in most languages. If you don’t know what a switch statement is Google it. Based on the priority of the newTodo, the priority label gets updated with one of three words (High, Medium, Low). The [self setNeedsDisplay] tells the cell to redisplay itself after this todo has been set.

Now, let’s add the code that lays out the cell.

This method gets called automatically when a UITableViewCell is being displayed. It tells the UITableView how to display your cell. The define statements are similar to define statements in C. The reason we are coding like this is because we can tweak these variables to get the display to our liking. First, we call the layoutSubviews of the super class. Next, we get a reference to the contentView.bounds. This variable will allow us to figure out how much drawing area we have and allow us to line objects up properly.

The if(!self.editing) part is not neccessary but is good practice. You would use this if you allowed editing of your cells. This code is a little tough to explain by typing, but I will do the best that I can. First, we declare our right-most column. This is done by making a frame to hold the content. This column will hold the text of the todo item. Most of the code here is just positioning. You can play with these numbers and see how it moves stuff around. Once all of the positioning code is completed, the frame of our todoTextLabel gets set to this newly created frame. This is done for each of our UI components. You can lay them out however you like, as I may not have the best layout.

We have one more method to override. It’s the setSelected method. Go ahead and add the following code.

This method gets called when the user taps on a given cell. We need to tell the cell how to behave when it gets tapped on. This method should look pretty straight forward. First, we call the setSelected method of the super class. Next, we update the background color depending on whether or not the cell was selected. Finally, the labels get set to a white color if the cell gets selected. This is to contrast the blue color that the background becomes when the cell is selected.

This last 2 methods that I want to talk about are the helper methods that we used earlier in the code. Add the following methods to your code.

newLabelWithPrimaryColor

This method got called when we were initializing our UILabels. It takes a few parameters that should be pretty self explanatory. Looking through the code, we first see the font being initialized with the size that we specified. If bold was specified this is also accounted for. Next, we instantiate a new UILabel and give it some properties. Finally, this newly created UILabel gets returned.

imageForPriority

This method is actually quite simple. It simply takes a priority and returns the UIImage that is associated with that priority. Notice the default clause. I decided to handle it like this instead of doing “case 1″ to handle all other cases. For whatever reason, if there is ever a priority that is not 1,2 or 3 it will, by default, have low priority.

Now that we have created our UITableViewCell, we need to display it in the table. Open up RootViewController.m and add the following import statement. This will allow us to use our TodoCell object.

Now find the numberOfRowsInSection method and add the following code

I’m not going to really go over this, as this is almost the exact same code as in the Fruits example. Basically, we are returning the number of todo items.

Now for the magic…We will now add our TodoCell to allow it to be displayed. Find the cellForRowAtIndexPath method and add the following code.

This code is fairly similar to the default code that Apple has provided us. The first change is we are instantiating our TodoCell object. We are creating it with the initWithFrame method and passing our identifier to it. Next, we get reference to the application’s appDelegate and use it to look up the todo item at the given index. This should be familiar. Finally, we set the todo item of the cell to the todo item at the row index and return the cell. That’s it! Go ahead and click the Build and Go icon and see your todo list come to life. Here is a screenshot of what your app should look like.

That concludes part 2 of this tutorial. Join me next time as I show you how to display detailed todo info using some new UI controls that we haven’t seen yet. As always, post your questions and comments in the comments section of the blog. Download The Sample Code

Happy iCoding!

iPhone Programming Tutorial – Creating a ToDo List Using SQLite Part 1

brandontreb — Tue, 19 Aug 2008 17:46:15 +0000

If you have been following my tutorials, you know that we have been working primarily with UITableViews. This is mostly because SO many applications can be developed using this simple control. This final UITableView tutorial will be taking all of the skills learned from previous tutorials, putting them all together, and adding SQLite to create a prioritized To-Do list. I will also be showing you how to add multiple columns to your table cells and we will be exploring some of the other controls that the iPhone has to offer. What good would the tutorials be if we didn’t use them to create something useful.

I will move a little faster in this tutorial while still explaining the new stuff in detail. I will assume that you have completed the fruits tutorial and it’s prerequisites.

This tutorial will be a multipart series as it will be a little longer than my previous ones. In this first tutorial, you will learn:

Create a NavigationBased Application
Create a Database
Add the Database to Your Project
Add the SQLite3 Framework
Create a Todo Class Object
Initialize the Database

So let’s get started…

Open up X-Code and Select File->New Project… Select Navigation-Based Application and click Choose…

Name your project todo. Now let’s create the todo database that we will be using. Open up the Terminal application on your Mac. This is located in Applications > Utilities.

If you have installed XCode, you should have mysqlite3 already on your computer. To check this, type:

sqlite3 into the Terminal and sqlite3 should start. Type .quit to exit. If sqlite3 is not installed, install all of the XTools from your Mac Installation Disk.

Now that the terminal is open let’s create the database. This is done with the command:

sqlite3 todo.sqlite

SQLite3 will now start and load the todo.sqlite database. By default the database is empty and contains no tables. If you need a refresher on the basics of SQL databases Google It. Since our application is fairly simple, we only need to create one table. We will create a table called todo by typing the following statement:

CREATE TABLE todo(pk INTEGER PRIMARY KEY, text VARCHAR(25), priority INTEGER, complete BOOLEAN);

One thing to note here is the pk field. It is the primary key of the table. This adds functionality such that every time a row is added to the database, it auto-increments this field. This will be a unique identifier to identify each row. All of the other fields should be fairly self explanitory.

Now that our table has been created, let’s add some data. We will eventually be adding todo items within our app, but for now we will add some defaults. Type the following commands below.

INSERT INTO todo(text,priority,complete) VALUES('Take out the trash',3,0); INSERT INTO todo(text,priority,complete) VALUES('Do Computer Science homework',1,0); INSERT INTO todo(text,priority,complete) VALUES('Learn Objective C',1,0); INSERT INTO todo(text,priority,complete) VALUES('DIGG this tutorial',2,0);

You can add as many todo items as you would like. For this tutorial, make sure you enter a priority between 1 and 3 (You’ll see why later). Now our database has been created and populated let’s exit out of SQLite3. Do this by typing .quit. Your terminal window should look something like this.

Now go back to XCode. Do a Control-Click (right click) on the folder named Resources. Click Add -> Existing Files… and browse to your todo.sqlite file and click Add. It will then prompt you with a screen like this.

Make sure you check the box that says Copy items into destination group’s folder (if needed). You should now see the todo.sqlite file inside of the resource folder.

Now that we have added the database, we need to load the Objective C libraries so we can use it. Do a control-click (right click) on the Frameworks folder. Click Add -> Existing Frameworks. Now this part is a little strange. It has been my experience that these libraries are not in the same place on all machines. So in the search bar type in libsqlite3. The file we are looking for is called libsqlite3.0.dylib. This may pull up multiple files as OSX has it’s own versions of this file. Just click on the largest of the files that show up and click Add. As you can see, mine is about 1.7 MB.

Now it should add the framework and your directory will look something like this:

We need to create an object to hold our todo information. We will eventually be making an array of these objects to populate a UITableView. Go ahead and click File -> New File… Select NSObject Subclass and click Next.

Name this object todo.m and check the box that says Also create “Todo.h” and click Finish.

Open up todo.h and add the following code.

We see some new things here…First, there is a variable of type sqlite3 called database. This will be a reference to the applications database and will allow the todo object to communicate with it. Make sure you add a #import in your imports.

Next, we see a primary key. Notice that in the property declaration it has the keywords assign and readonly. This tells the compiler that this variable, once assiged, can not be changed again. This is good since each todo will be uniquely identified by this variable.

Also, I have declared a method called initWithPrimaryKey. This will be the contstructor for this object. It takes an integer to assign as the primary key and an sqlite3 object to use as the database reference.

Let’s implement this method…Open up todo.m and add the following code.

There are quite a few new things that need to be explained here. I will just go through it line by line.

static sqlite3_stmt *init_statement = nil

This will hold our initialize statement when retrieving todo data from the database. This statement is static, meaning it is independent of any instance. In other words, there will be only one of them no matter how many todo objects we create. This statement will get compiled and allow us to do some neat things. I’ll explain more in a bit.

The next lines makes sure that the super class (NSObject) initilizes properly before we initilize a todo object. We then set the local primary key and database objects to the parameters passed to the initWithPrimaryKey method.

Now some interesting stuff happens. The next lines checks if our init_statment is null. This will happen only once per launch of the application. If it is null, we create a new string containing an SQL statement. If you are familiar with SQL at all, this should look pretty familiar with one exception. What is a question mark doing in there? Well, I will tell you. After the SQL statement gets compiled, we can bind a value to it that will eventually replace the question mark. So this allows us to have 1 generic SQL statement, but bind different values to it to retrieve different results. So the next line, you guessed it, prepares the statement and stores it in our init_statement. The if statement just checks to see if this finished correctly and prints an error if there was a problem.

Moving on… The line sqlite3_bind_int simply replaces that question mark with the primary key of the current todo object, so what we end up with is statements like this:

SELECT text FROM todo WHERE pk = 1; SELECT text FROM todo WHERE pk = 2; SELECT text FROM todo WHERE pk = 3; SELECT text FROM todo WHERE pk = n;

After that, the sqlite3_step(init_statement) method is called. This method executes the SQL statement on the database. It is contained inside of an if statement to make sure it executed properly. Now we can finally access the todo data. We see this line:

self.text = [NSString stringWithUTF8String:(char*) sqlite3_column_text(init_statement,0)];

Wow, that’s a mouthful… Let’s analyze it. The sqlite3_column_text method tells SQL that we want to retrieve a string object from the database. It has 2 parameters. The first, is just a reference to the SQL statement that was used. The second is the column number that we wish to get text from. So in this case, we only have one column (SELECT text FROM…) so there is only 1 index and that’s the 0th index. Next, the (char *) is just a cast to a string (might not be needed, but good practice). And finally, we build an NSString object with the data returned so that we can assign self.text to it.

This is quite a bit to explain in just text. If I have lost you, feel free to ask me questions in the comments.

We are done with the todo object for now…

Go ahead and open up todoAppDelegate.h and add the following code.

This should look a little familiar with the exception of a few lines. Notice that I have created an NSMutableArray of todo objects. This will be (like the fruit example) an array to hold our todo items. We will eventually use this array to populate a UITableView. The only new lines here are the import of sqlite3.h and the sqlite3 *database line. Now let’s open up todoAppDelegate.m and add some code.

One new thing we see here is a private interface. We declared it here because it’s specific to this object so it does not need to be declared in the .h file. The 2 functions we will implement are createEditableCopyOfDatabaseIfNeeded and initializeDatabase. Much of the code for these has already been written for us inside of Apple’s SQLBooks tutorial. I will going through this code and explaining it the best that I can. Add the following code.

What this method is essentially doing is copying the database from your project folder to the documents folder on your iPhone. This will only happen once as it first checks if the database already exists in the documents folder. I’m not going to go through this line by line as it is fairly self explanitory. Apple does a great job of naming functions and variables so that we can understand what is going on. If I get enough requests in the comments, I’ll do a line-by-line writup of this function.

The next function we will implement is initializeDatabase. Add the following code:

That’s a lot of text! Don’t worry it’s mostly comments. Let’s analyze this code…Some of it is very similar to the fruits example.

The first line creates and initializes a NSMutableArray. We then go on to set this array to our object’s todos array and release the temporary object.

The next 3 lines locate the database we created inside of the documents folder. Following that, the sqlite3_open line open’s the database so we can access its data. If the database opens correctly, we then proceed to retrieve todo items. The first line:

const char *sql = "SELECT pk FROM todo";

is an SQL statement that we will use to get all of the primary keys from the database. We then prepare the statement (as we did inside the todo.m file) only this time there is no “?” in the statement. That is because there is not condition for retrieving the primary keys. We are simply saying “give me all of the primary keys in the database”.

Now we see a while loop that is stepping through the SQL results. Every time we call sqlite3_step, the next result gets retrieved. The line:

int primaryKey = sqlite3_column_int(statement,0);

retrieves the primary key from each result. This is very similar to retrieving the text in the todo.m class only we use the sqlite3_column_int method instead of the sqlite3_column_text method. This is done for obvious reasons.

After we have the primary key, we create a new Todo object and call the initWithPrimaryKey constructor that we created. The primary key gets passed as well as a reference to the database. This allows the Todo object to essentially “look itself up” in the database. Finally, we add the newly created Todo object to our array of todos.

The last statement sqlite3_finalize clears the statement from memory and does some other cleanup.

The last part of this tutorial is calling these functions to create and initialize the database. So add the following code to applicationDidFinishLaunching:

We are simply calling these functions. You can now click Build and Go but your application won’t display anything! You might be quite frustrated that you completed this portion of the tutorial and have yet to see anything. Well, stay tuned! I will have the next portion of this tutorial up soon.

For you ambitious programmers you could move on. If you notice, at this point we are in a similar situation as the fruit tutorial. We have an Array of objects that will eventually populate a UITableView.

This tutorial will be a 4 part series and I will show you how to use a few more controls. We will be adding, editing, and deleting todo items. If you have any questions, please leave them in the comments. Also, if you get lost you can download the sample code here

Happy iCoding!