Aperture MetaWeblog Plugin: Initial Setup

Creating a temporary Aperture Library

Now is a good time to create a temporary Aperture library and add a few pictures to it. This is done to avoid corrupting your current library when you are debugging the system and prematurely kill the application. You can do that by:

1. Quit Aperture if its running
2. Rename the existing library to something
3. Start Aperture, which will create a new Library in your Pictures folder
4. Quit Aperture
5. Rename the new Library to something like "Temporary Aperture Library"
6. Rename the old Library back to "Aperture Library"
7. Start Aperture
8. In the preferences, change the library location to "Temporary Aperture Library".
9. Restart Aperture

Create XCode Project

Start XCode. Select File, then New, then Project.

In the New Project dialog, select Standard Apple Plug-ins and then select Aperture Export Plug-In.

Select Choose...

Select the location where you want to save the project and select Save. In my case, I saved it in "~/Projects/Aperture/MetaWeblogPlugIn".

Modifying the Xcode project

Build the Xcode project. You'll notice 27 errors in total. These errors forces us to specify values for the plug-in. All the errors are in "MetaWeblogPlugIn.m". To understand the changes, you'll need to reference the Aperture 2.1 SDK Reference. We should also call shouldCancelExport, shouldFinishExport and shouldBeginExport of _exportManager at the appropriate times. Here is the revised file that no longer fails to build and calls the respective methods of exportManager.

#import "MetaWeblogPlugIn.h"

@implementation MetaWeblogPlugIn

 - (id)initWithAPIManager:(id<PROAPIAccessing>)apiManager
{
  if (self = [super init])
  {
    _apiManager  = apiManager;
    _exportManager = [[_apiManager apiForProtocol:@protocol(ApertureExportManager)] retain];
    if (!_exportManager)
      return nil;
    
    _progressLock = [[NSLock alloc] init];
    
    // Finish your initialization here
  }
  
  return self;
}

- (void)dealloc
{
  // Release the top-level objects from the nib.
  [_topLevelNibObjects makeObjectsPerformSelector:@selector(release)];
  [_topLevelNibObjects release];
  
  [_progressLock release];
  [_exportManager release];
  
  [super dealloc];
}


#pragma mark -
// UI Methods
#pragma mark UI Methods

- (NSView *)settingsView
{
  if (nil == settingsView)
  {
    NSBundle *myBundle = [NSBundle bundleForClass:[self class]];
    NSNib *myNib = [[NSNib alloc] initWithNibNamed:@"MetaWeblogPlugIn" bundle:myBundle];
    if ([myNib instantiateNibWithOwner:self topLevelObjects:&_topLevelNibObjects])
    {
      [_topLevelNibObjects retain];
    }
    [myNib release];
  }
  
  return settingsView;
}

- (NSView *)firstView
{
  return firstView;
}

- (NSView *)lastView
{
  return lastView;
}

- (void)willBeActivated
{
  
}

- (void)willBeDeactivated
{
  
}

#pragma mark
// Aperture UI Controls
#pragma mark Aperture UI Controls

- (BOOL)allowsOnlyPlugInPresets
{
  return TRUE;  
}

- (BOOL)allowsMasterExport
{  
  return FALSE;  
}

- (BOOL)allowsVersionExport
{
  return TRUE;  
}

- (BOOL)wantsFileNamingControls
{
  return TRUE;  
}

- (void)exportManagerExportTypeDidChange
{
  
}


#pragma mark -
// Save Path Methods
#pragma mark Save/Path Methods

- (BOOL)wantsDestinationPathPrompt
{
  return FALSE;
}

- (NSString *)destinationPath
{
  return nil;
}

- (NSString *)defaultDirectory
{
  return nil;
}


#pragma mark -
// Export Process Methods
#pragma mark Export Process Methods

- (void)exportManagerShouldBeginExport
{
  [_exportManager shouldBeginExport];
}

- (void)exportManagerWillBeginExportToPath:(NSString *)path
{

}

- (BOOL)exportManagerShouldExportImageAtIndex:(unsigned)index
{
  return TRUE;
}

- (void)exportManagerWillExportImageAtIndex:(unsigned)index
{
  
}

- (BOOL)exportManagerShouldWriteImageData:(NSData *)imageData toRelativePath:(NSString *)path forImageAtIndex:(unsigned)index
{
  return TRUE;  
}

- (void)exportManagerDidWriteImageDataToRelativePath:(NSString *)relativePath forImageAtIndex:(unsigned)index
{
  
}

- (void)exportManagerDidFinishExport
{
  [_exportManager shouldFinishExport];
}

- (void)exportManagerShouldCancelExport
{
  [_exportManager shouldCancelExport];
}


#pragma mark -
  // Progress Methods
#pragma mark Progress Methods

- (ApertureExportProgress *)progress
{
  return &exportProgress;
}

- (void)lockProgress
{
  
  if (!_progressLock)
    _progressLock = [[NSLock alloc] init];
    
  [_progressLock lock];
}

- (void)unlockProgress
{
  [_progressLock unlock];
}

@end

Aperture plugins are located in one of the following locations:

1. ~/Library/Application Support/Aperture/Plug-Ins/Export
2. /Library/Application Support/Aperture/Plug-Ins/Export

By default, the Xcode project does not deploy the plug-in to either one of these locations. This is rather inconvenient, so lets modify the Xcode project to do so automatically. In the project, select Targets and then MetaWeblogPlugIn (or whatever you called your plugin). Right-click on the target MetaWeblogPlugIn and select Get Info.

Now select the Build tab, and browse to the Deployment section. Ensure the Deployment Location is selected.

Change the configuration to "Release" and repeat the step. Build the project again. You should now see your plug-in in the location "~/Library/Application Support/Aperture/Plug-Ins/Export". There is one more step we need to take before we can run the plug-in. We need to modify "info.plist" with information that will identify our plug-in. Double-click on the "info.plist".

Change the "yourcompany" text in the Bundle Identiier to the name of your name, organization, company or website domain; the displayName to "Blog" (or any text you want to display in the menu); the helpURL to a location on your website, or that of your organization and the uuid to a unique UUID. To generate a UUID, start a terminal session, and enter uuidgen, followed by return.

Replace the "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx" text with the text generated by uuidgen. In this case, uuidgen generated "090F0BE8-EA52-4794-9806-417C5DD6DEE8". Save "Info.plist" and rebuild the project.

Testing the plug-in

Start Aperture. Select File, then Export and notice that the plug-in is visible.

Select Blog (or whatever you set the displayName to).

You can modify a few settings and select Export when you are done. You will not be asked a location where to save the plug-in. The pictures are stored in the "Aperture Export" folder. Since we will upload the image to a blog in a future version of this plug-in, there is no reason for us worry about actually saving the image. It is just nice to know it works.

A final note... debugging

Currently its not possible to run Aperture and the plug-in from within the Xcode project. We can change that by adding an executable. In the Xcode project, right click on Executables and select New Custom Executable.

The New Custom Executable dialog will appear.

Enter Aperture as the executable name and "Applications/Aperture.app" as the executable path (assuming that is where Aperture is running from). Select Finish. The Executable "Aperture" Info dialog appears.

Since we have nothing to modify, just close the window. If Aperture is running, terminate it. From Xcode, select Build and Go. Validate that Aperture starts up. Being adventurous? Try an debug your plugin.

Conclusion

This entry contains my crib notes on how to setup an Aperture project.

References

1. There are Aperture Export Plug-In tutorials at http://www.bagelturf.com/