XCode tutorial

1. Prerequisites
2. Create new project
1. Project template
3. Create the application controller
1. New class
2. New objectivec class
3. Midgard headers
4. Instantiate the controller
1. Editing resource
2. Object
3. Resource contents
4. Class identity
5. Build & watch
1. Output
6. Extending

Prerequisites

This is short tutorial about getting started with Midgard on the Mac. We're going to create a simple Cocoa application.

• XCode 3.1.2 (latest at the moment)
• Installed Midgard package bundle

Create new project

To get started lunch XCode and choose New project from the File menu. Pick Midgard and Midgard Application as your template of choice:

In the following screen choose a location and a name where your fresh project will be stored. For this tutorial I decided to name the application: MidgardApp.

When the project is created try building and lunching it (the green play button with a hammer). It should work fine and show an empty window on the screen.

Create the application controller

For a good start we need to add a main controller to our application -- a standard procedure for most Cocoa apps. This controller will do some Midgard work for us. Ctrl-click the Classes group in the organizer and pick Add->New File.

Choose "ObjectiveC class":

Name the file AppController.m and make sure that Also create AppController.h option is checked.

When the new class appears in Classes category double click the interface declaration for it (AppController.h) and add an extra import directive to include the Midgard header files:

#import <Midgard/Midgard.h>

Now open the actual implementation of the controller -- the AppController.m file. We'll add a new function -- awakeFromNib. This method is called (once) when the object is being instantiated from the resource container. So, we can say it's a startup funcion. The implementation:

... 
@implementation AppController

-(void)awakeFromNib
{
  // Initialize midgard -- this is required
  [MGDContext initialize];

  // Use default configuration
  MGDConfig *config = [[MGDConfig alloc] init];
  [config readResource:@"midgard.conf"];

  // Create a connection
  MGDConnection *connection = [[MGDConnection alloc] init];
  [connection openConfig:config];
  [config createMidgardTablesForConnection:connection];

  // Create new person object
  MGDObject *person = [[MGDObject alloc] initWithConnection:connection
                                                andTypeName:@"midgard_person"];

  [person setValue:@"John" forKey:@"firstname"];
  [person setValue:@"Doe" forKey:@"lastname"];

  [person create];
  NSLog(@"Created new person with guid: %@", [person guid]);

  // List all the people
  MGDQueryBuilder *qbuilder = [[MGDQueryBuilder alloc] initWithConnection:connection
                                                             andClassName:@"midgard_person"];

  for (MGDObject *o in [qbuilder execute]) {
    NSLog(@"- %@ %@", [o valueForKey:@"firstname"], [o valueForKey:@"lastname"]);
  }

  // Free
  [person release];
  [qbuilder release];
  [connection release];
  [config release];
}

@end
...

This code:

• Initializes Midgard and the type system
• Creates a standard Midgard connection with the default configuration. The config is read from the conf file that's embedded in the project as a resource.
• Creates a new object of type midgard_person
• Sets some parameters on it
• Saves it into the database and prints the guid of the new object
• Performs a query on the database listing all existing objects of type midgard_person
• Closes the connection and releases the memory

You can compile to make sure there are no errors and everything is fine. However, the program will not produce any output just yet. Our code is not performed because the object is not yet instantiated in any way (it's not awoken).

Instantiate the controller

We're going to edit the MainMenu.xib resource file. Double click it in the organizer to lunch the interface builder:

We need to add a new object instance to the resource file (bundle). In the Library palette find the Object element (blue cube icon):

...and drag&drop it to the MainMenu.xib window which contains the list of elements in the active resource. When done it should look like:

Currently our object has a default class -- NSObject (the base class of all Foundation objects in ObjectiveC). We need to make it specialized -- make it an instance of the AppController class we just created.

To do so select the object and look at the inspector palette. Pick the Object identity pane and replace NSObject with AppController. This is a class name.

Build & watch

Now save the resource file and build & run the project. The object AppController is now instantiated with the default window and our awakeFromNib code is being executed. The output should look like:

The application can be now copied to any other mac machine (with or without Midgard) and will work just fine.

Extending

If you look at the resource files included in the project you'll notice a few Midgard-specific files. Those are: midgard.conf (contains the database configuration, etc.) , MgdObjects.xml (containing the base schema) and mgd_initial_database.xml (with initial database settings).

Tagged

vinland

objc