1. Project RequirementsI suggest that you have at least a basic understanding of SQLite, writing SQL statements, the XCode interface and using the terminal in OSX. If you don't know anything about any of these topics then this tuto
rial probably isn't for you.
2. Creating our SQLite database for our tutorialWe first need to create a database for use with our application. For the purposes of this tutorial we will be building a database of shingles along with a little information on them and a picture.
Fire up a new Terminal window and make a new folder to store the database in, here are the commands I ran
cd /Users/lookaflyingdonkey/Documents
mkdir RoofSQLite
cd RoofSQLite
sqlite3 ShingleDatabase.sql
You should now be at a "sqlite" command prompt, this is where we will be building our database structure and entering some test data.
For our example we need the name of the shingle, a short description and a link to an image, price infomation, store name. Follow the commands below to create the table and to enter some sample data.
CREATE TABLE shingles ( id INTEGER PRIMARY KEY, name VARCHAR(50), description TEXT, image VARCHAR(255) );
INSERT INTO shingles (name, description, image) VALUES ('Elephant', 'The elephant is a very large shingle that lives in Africa and Asia', 'http://dblog.com.au/wp-content/elephant.jpg');
INSERT INTO shingles (name, description, image) VALUES ('Monkey', 'Monkies can be VERY naughty and often steal clothing from unsuspecting tourists', 'http://dblog.com.au/wp-content/monkey.jpg');
INSERT INTO shingles (name, description, image) VALUES ('Galah', 'Galahs are a wonderful bird and they make a great pet (I should know, I have one)', 'http://dblog.com.au/wp-content/galah.jpg');
INSERT INTO shingles (name, description, image) VALUES ('Kangaroo', 'Well I had to add the Kangaroo as they are the essence of the Australian image', 'http://dblog.com.au/wp-content/kangaroo.jpg');
The first command will create the table with the required structure and the next four will insert some test data for us to work with.
To ensure that you have entered the data correctly you can execute "SELECT * FROM shingles;" and see if it returns the items above.
Once you are confident that everything had been created successfully you can leave the sqlite command line by typing ".quit".
3. Creating our ProjectNow that our database is all ready to go we need to setup our X-Code project.
Start off by creating a new "Navigation-Based Application".
Give your Project a name, I called mine "RoofSQLite".
Now set your screen layout to how you prefer it, I suggest making the window as large as possible, and making the code view as tall as possible by dragging the horizontal slider to the top. This will allow yo
u the most room to move when building your application.
Now its time to create the required classes and views for our application, we will start off by making our views.
Right Click on the "Resources" folder in the left hand pane and click "Add File", we want to create a new "View XIB" under the "User Interfaces" group.
We now need to give it a name, to stick the Apple's naming conventions we are going to call it "ShingleViewController.xib", Now Click "Finish".
Now we need to create two classes, the first one will represent an shingle, right click on the "Classes" folder in the left hand pane, click "Add > New File?", choose the "NSObject subclass" template under th
e "Cocoa Touch Classes" group and name it "Shingle".
The second class will be for our ShinglesViewController, right click on the "Classes" folder in the left hand pane, click "Add > New File?", choose the "UIViewController subclass" under the "Cocoa Touch Class
es" group and name it "ShingleViewController".
4. Adding SQLite Framework and our Shingle DatabaseNow that we have created all of our views and classes it is time to start the real grunt work.
First off we need to include the SQLite libraries so our application can utilise them. To do this you will need to right click on the "Frameworks" folder in the left hand pane, then click on "Add > Existing F
rameworks?", then navigate to "/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS2.0.sdk/usr/lib/" and double click the "libsqlite3.0.dylib" file. A popup will appear, just click "Add" and the lib
rary will be added to your project.
We also need to add our database we created earlier to the Resources folder, to do this simply right click on the "Resources" folder, click "Add > Existing Files?", navigate to the location you created the da
tabase in then double click on the ShingleDatabase.sql file. Another popup will appear, just click add.
All done with the importing, time to code!
5. The Coding begins!We are going to start the coding by building our "Shingle" object, every shingle will have 3 properties, a name, a description and an image URL.
Open up the "Shingle.h" file from the "Classes" folder and edit its contents to look like below,
#import <UIKit/UIKit.h>
@interface Shingle : NSObject {
NSString *name;
NSString *description;
NSString *imageURL;
}
@property (nonatomic, retain) NSString *name;
@property (nonatomic, retain) NSString *description;
@property (nonatomic, retain) NSString *imageURL;
-(id)initWithName:(NSString *)n description:(NSString *)d
http://www.blogger.com/(NSString *)u;
@end
Most of the above code should be pretty familiar to you, the only thing that may not be is the initWithName line, this line will allow us to create a new object with the required data, we could have used the
default init function, but it will be easier for us to define our own.
Now we will actually have to implement the Shingle Object, open up the "Shingle.m" file and edit its contents to look like below:
#import "Shingle.h"
@implementation Shingle
@synthesize name, description, imageURL;
-(id)initWithName:(NSString *)n description:(NSString *)d
http://www.blogger.com/(NSString *)u {
self.name = n;
self.description = d;
self.imageURL = u;
return self;
}
@end
The above code should be pretty easy to read as well, it basically stores the supplied data from the initWithName function and return the object (self).
Now its time to setup the Application delegate to access the database.
Open up the "RoofSQLiteAppDelegate.h" and edit its contents to look like below:
#import <UIKit/UIKit.h>
#import <sqlite3.h> // Import the SQLite database framework
@interface RoofSQLiteAppDelegate : NSObject {
UIWindow *window;
UINavigationController *navigationController;
// Database variables
NSString *databaseName;
NSString *databasePath;
// Array to store the shingle objects
NSMutableArray *shingles;
}
@property (nonatomic, retain) IBOutlet UIWindow *window;
@property (nonatomic, retain) IBOutlet UINavigationController *navigationController;
@property (nonatomic, retain) NSMutableArray *shingles;
@end
What we are doing here is importing the SQLite database framework and creating some variables for storing the database details and an array of shingle objects.
Now open up the "RoofSQLiteAppDelegate.m" file and edit its contents to look like below:
#import "RoofSQLiteAppDelegate.h"
#import "RootViewController.h"
#import "Shingle.h" // Import the shingle object header
@implementation RoofSQLiteAppDelegate
@synthesize window;
@synthesize navigationController;
@synthesize shingles; // Synthesize the aminals array
- (void)applicationDidFinishLaunching:(UIApplication *)application {
// Setup some globals
databaseName = @"ShingleDatabase.sql";
// Get the path to the documents directory and append the databaseName
NSArray *documentPaths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
NSString *documentsDir = [documentPaths objectAtIndex:0];
databasePath = [documentsDir stringByAppendingPathComponent:databaseName];
// Execute the "checkAndCreateDatabase" function
[self checkAndCreateDatabase];
// Query the database for all shingle records and construct the "shingles" array
[self readShinglesFromDatabase];
// Configure and show the window
[window addSubview:[navigationController view]];
[window makeKeyAndVisible];
}
- (void)applicationWillTerminate:(UIApplication *)application {
// Save data if appropriate
}
- (void)dealloc {
[shingles release];
[navigationController release];
[window release];
[super dealloc];
}
-(void) checkAndCreateDatabase{
// Check if the SQL database has already been saved to the users phone, if not then copy it over
BOOL success;
// Create a FileManager object, we will use this to check the status
// of the database and to copy it over if required
NSFileManager *fileManager = [NSFileManager defaultManager];
// Check if the database has already been created in the users filesystem
success = [fileManager fileExistsAtPath:databasePath];
// If the database already exists then return without doing anything
if(success) return;
// If not then proceed to copy the database from the application to the users filesystem
// Get the path to the database in the application package
NSString *databasePathFromApp = [[[NSBundle mainBundle] resourcePath] stringByAppendingPathComponent:databaseName];
// Copy the database from the package to the users filesystem
[fileManager copyItemAtPath:databasePathFromApp toPath:databasePath error:nil];
[fileManager release];
}
-(void) readShinglesFromDatabase {
// Setup the database object
sqlite3 *database;
// Init the shingles Array
shingles = [[NSMutableArray alloc] init];
// Open the database from the users filessytem
if(sqlite3_open([databasePath UTF8String], &database) == SQLITE_OK) {
// Setup the SQL Statement and compile it for faster access
const char *sqlStatement = "select * from shingles";
sqlite3_stmt *compiledStatement;
if(sqlite3_prepare_v2(database, sqlStatement, -1, &compiledStatement, NULL) == SQLITE_OK) {
// Loop through the results and add them to the feeds array
while(sqlite3_step(compiledStatement) == SQLITE_ROW) {
// Read the data from the result row
NSString *aName = [NSString stringWithUTF8String:(char *)sqlite3_column_text(compiledStatement, 1)];
NSString *aDescription = [NSString stringWithUTF8String:(char *)sqlite3_column_text(compiledStatement, 2)];
NSString *aImageUrl = [NSString stringWithUTF8String:(char *)sqlite3_column_text(compiledStatement, 3)];
// Create a new shingle object with the data from the database
Shingle *shingle = [[Shingle alloc] initWithName:aName description:aDescription
http://www.blogger.com/aImageUrl];
// Add the shingle object to the shingles Array
[shingles addObject:shingle];
[shingle release];
}
}
// Release the compiled statement from memory
sqlite3_finalize(compiledStatement);
}
sqlite3_close(database);
}
@end
Now I know that may look like a fair bit of code and it probably also looks quite scary!
But really it is quite simple and I have tried to comment nearly every line to describe to you what the line does and why it is there.
The checkAndCreateDatabase function checks to see if we have already copied our database from the application bundle to the users filesystem (in their documents folder), if the database hasn't already been cr
eated or it has been removed for some reason it will be recreated from the default database.
Next the readShinglesFromDatabase function will make a connection to the database that is stored in the users documents folder, and then executes the SQL statement "SELECT * FROM shingles". It will then go th
rough each row that is returned and it will extract the name, description and imageURL from the result and build an Shingle object for each. You will see the "sqlite3_column_text" function used here, there ar
e many more of these for returning other field types such as "sqlite3_column_int" for integers, "sqlite3_column_blob" for blobs or "sqlite3_column_value" to get an unknown value.
Now that we have the data in our array and we have it in our known format we are ready to start displaying it.
Open up the "RootViewController.m" file and edit the numberOfRowsInSection to look like the following:
RoofSQLiteAppDelegate *appDelegate = (RoofSQLiteAppDelegate *)[[UIApplication sharedApplication] delegate];
return appDelegate.shingles.count;
What this does is it creates a link to the application delegate, and then the second line returns the size f the shingles array in out Application delegate, this array was filled previously from the SQLite da
tabase.
Now in the cellForRowAtIndexPath function you will need at change it to look like the following:
- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {
static NSString *CellIdentifier = @"Cell";
UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:CellIdentifier];
if (cell == nil) {
cell = [[[UITableViewCell alloc] initWithFrame:CGRectZero reuseIdentifier:CellIdentifier] autorelease];
}
// Set up the cell
RoofSQLiteAppDelegate *appDelegate = (RoofSQLiteAppDelegate *)[[UIApplication sharedApplication] delegate];
Shingle *shingle = (Shingle *)[appDelegate.shingles objectAtIndex:indexPath.row];
[cell setText:shingle.name];
return cell;
}
We pretty much just added 3 lines under the "// Set up the cell" line.
The first one is the same as we added previously to access the application delegate.
The second line creates a new Shingle object based on the array from the application delegate, it will be used to create a row for each individual record in the database.
On the final line we are just setting the text of the cell to the name field from the Shingle object.
You can now run the program and you should see a table view with the 4 shingles we added to the database, if you added more than my default shingles you should see them in here as well.
We will now setup the ShingleViewController, open up the "ShingleViewController.h" file and edit its contents to below:
#import <UIKit/UIKit.h>
@interface ShingleViewController : UIViewController {
IBOutlet UITextView *shingleDesciption;
IBOutlet UIImageView *shingleImage;
}
@property (nonatomic, retain) IBOutlet UITextView *shingleDesciption;
@property (nonatomic, retain) IBOutlet UIImageView *shingleImage;
@end
What we are doing above is adding an outlet for the description and image for the Shingle, we will use these later on when we link the view up.
Now open up the "ShingleViewController.m" file and add a synthesize call for for the description and image, this will go under the "@implementation ShingleViewController" line, like so:
#import "ShingleViewController.h"
@implementation ShingleViewController
@synthesize shingleDesciption, shingleImage;
Now it is time to make the detailed view page appear when you select a record. Open up the "ShingleViewController.xib" file from the resources folder and the interface builder should appear.
The first thing we need to do is to set the File's Owner Class to ShingleViewController, this is done by selecting the "File's Owner" item in the main window and then clicking Tools > Identity Inspector in th
e top menu, and then selecting ShingleViewController from the class dropdown.
Your inspector window should now look like this:
We are going to be using a UITextView for the description (as it will allow for word wrapping and scrolling in the case that the description is quite large) and a UIImageView to display the image. I have laid
mine out like below:
Now that we have everything laid out it is time to link them all up, start by holding control and click+drag from the "File's Owner" to the "View" objects, a little gray menu will appear and you will need to
select view. Now hold control and click+drag from the "File's Owner" to the UITextView in the layout window, you should see "shingleDescription" in the popup list, select it. Repeat this process for the UIIma
geView and you should see shingleImage appear, select it also.
Now save the interface and close the interface builder.
Nearly done! All we have to do now is to setup the code for when a user presses on a record in the table view.
Open up the "RootViewController.h" file and edit its contents to below:
#import <UIKit/UIKit.h>
#import "ShingleViewController.h"
@interface RootViewController : UITableViewController {
ShingleViewController *shingleView;
}
@property(nonatomic, retain) ShingleViewController *shingleView;
@end
We are creating an instance of the ShingleViewController to be used bu the RootViewController when a user presses on an item.
Now open up the "RootViewController.m" file and edit the top part of the file to look like below:
#import "RootViewController.h"
#import "RoofSQLiteAppDelegate.h"
#import "Shingle.h"
@implementation RootViewController
@synthesize shingleView;
This will just synthesize the shingleView that we just added.
First up lets set the default title of our view, to do this you need to uncomment the viewDidLoad function, and edit it to below:
- (void)viewDidLoad {
[super viewDidLoad];
// Uncomment the following line to add the Edit button to the navigation bar.
// self.navigationItem.rightBarButtonItem = self.editButtonItem;
self.title = @"My Zoo";
}
We also need to edit the didSelectRowAtIndexPath
function in this file, edit it to look like below:
- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath {
// Navigation logic -- create and push a new view controller
RoofSQLiteAppDelegate *appDelegate = (RoofSQLiteAppDelegate *)[[UIApplication sharedApplication] delegate];
Shingle *shingle = (Shingle *)[appDelegate.shingles objectAtIndex:indexPath.row];
if(self.shingleView == nil) {
ShingleViewController *viewController = [[ShingleViewController alloc] initWithNibName:@"ShingleViewController" bundle:nil];
self.shingleView = viewController;
[viewController release];
}
// Setup the animation
[self.navigationController pushViewController:self.shingleView animated:YES];
// Set the title of the view to the shingle's name
self.shingleView.title = [shingle name];
// Set the description field to the shingles description
[self.shingleView.shingleDesciption setText:[shingle description]];
// Load the shingles image into a NSData boject and then assign it to the UIImageView
NSData *imageData = [NSData dataWithContentsOfURL:[NSURL URLWithString:[shingle imageURL]]];
UIImage *shingleImage = [[UIImage alloc] initWithData:imageData cache:YES];
self.shingleView.shingleImage.image = shingleImage;
}
What we are doing here is checking to see if the shingleView object has already been created, if not then create it.
The next few lines are used to setup the animation (slide from right to left) and to set the actual data fields to those of the selected shingle.
Now you should be ready to fire up the application and see it in all its glory.
--END--
Reference 1: http://dblog.com.au/iphone-development-tutorials/iphone-sdk-tutorial-reading-data-from-a-sqlite-database/
Reference 2:
http://mobileorchard.com/iphone-sqlite-tutorials-and-libraries/
