Mac Geekery

There’s nothing worse than an application that hides its data … no, your data from you. As a developer, you should take into account your experience as a user and avoid lock-in as much as possible, as well as enable useful “mashups” with other applications. To make it easier for users to use both your application and another with the same set of their data, you need to make it easy for users to get that data out of your application. You could support every common export type for your kind of data and hope that’s enough, or you could create a simple API to get at the data so that your users can do the work of making those exports. On the Mac, the easiest and most standard way of doing the latter is AppleScript.

With AppleScript you can setup a basic description of where you keep your data and let Cocoa Scripting take over and pull it all out of your program for you without you needing to change much at all. You’ll get features like searching and basic property editing for free. It’s quick, easy, and wonderful.

Unless you’re using Core Data. Like many other features in Mac OS X, gaining all the benefits of Core Data exempts you from the “easy” part that comes with the rest of the OS (like, oh, threading and autosave-enabled NSDocuments, for instance). It doesn’t make it impossible, it just makes it a very slight more interesting. In fact, making a read-only AppleScript interface is rather simple. Making a read/write interface is a minor pain in the posterior. Today, I’ll go over how to make a read-only interface and touch on the difficulties of making a read/write interface with Core Data. Later, I plan on covering the read/write interface when I’ve solved the ills of doing so and can explain how I got it to work. So much of this is “hold the bunny ears halfway up and lift your right leg towards the south” that it’s sometimes hard to say how something is working, or not.

To discuss this in detail, I’m going to go over creating a small program from scratch to store quick notes. You can follow along with me in Xcode if you like, or just skim to get the basics and add it to an existing project.

Ground Work

First, open up Xcode and create a new Core Data document-based project. Open the model and add an entity called Note. Give it two properties, “name” and “content” — both strings.

Now, make the code files for these objects the easy way. While still in the editor, press ⌘-N and pick Managed Object Class. This will give you an assistant to create stock class files with KVC accessor/mutators for each entity in the model. Cocoa’s easy, Core Data’s easier, and doing it in Xcode is the easiest of all.

Now, open the document in Interface Builder. Create a new array controller and call it Notes. In the inspector, set it to Entity mode and tell it to use the Note entity and to auto-prepare the content. Add a table view, a text field, and a text view to the window and bind them to the array controller on the keys you made in the model. Remember to turn off graphics and fonts in the view so you get the “value” binding that’s plain text.

In your document controller, you’ll need to make some data to play with. You could hook up buttons and connect them to add: and remove: but then you’d have to make new data every time or open a saved document or such. Just do something like the following in windowControllerDidLoadNib: to make it easier on yourself.

Note *theNote = [NSEntityDescription insertNewObjectForEntityForName:@“Note” inManagedObjectContext:[self managedObjectContext]];

[theNote setName:@“Note 1”];

[theNote setContent:@“Content 1”];


	
theNote = [NSEntityDescription insertNewObjectForEntityForName:@“Note” inManagedObjectContext:[self managedObjectContext]];

[theNote setName:@“Note 2”];

[theNote setContent:@“Content 2”];

	
theNote = [NSEntityDescription insertNewObjectForEntityForName:@“Note” inManagedObjectContext:[self managedObjectContext]];

[theNote setName:@“Note 3”];

[theNote setContent:@“Content 3”];

	
theNote = [NSEntityDescription insertNewObjectForEntityForName:@“Note” inManagedObjectContext:[self managedObjectContext]];

[theNote setName:@“Note 4”];

[theNote setContent:@“Content 4”];

Now run the application and you should see four notes pop up in the table and clicking on each should give you the content listed above. If not, fix it. You should be able to get this far on your own for this tutorial to be of much use to you.

Adding Support to Your Code

Now we need to add some basic methods to the model so as to identify it to Cocoa Scripting. You should have the code fleshed out and generally working before adding the scripting definition file, so we’ll get to that after this.

AppleScript wants a unique identifier for your object, and it needs to be one that it can come back to at any time and get the same object with. Cocoa Scripting uses the NSScriptObjectSpecifier class for that. It comes in several variants, one each for using an object’s index in an array, its name, or its unique ID. We’ll be using the unique ID because not every object has a name (or they may have duplicate names) and Core Data data is unordered.

To do this, you need two things on your model objects. First, some way of generating a unique ID. For this, we’ll use the internal Core Data ID for the object. There’s exactly one problem with this: that ID changes for unsaved objects when you save. Just be aware of that and ensure your users are aware as well. So, here’s that method:

- (NSString*) identifier
{
	return [[[self objectID] URIRepresentation] absoluteString];
}

Second, you’ll need to implement objectSpecifier and return a proper NSUniqueIDSpecifier object so that Cocoa Scripting can find the object if it needs to return to it. There’s just one problem with this, but to get to it I’ll need to explain object specifiers a little.

An object in AppleScript is rarely alone. Almost every object is a child of another object. For instance, a circle in Sketch is a circle in a document in the application Sketch. Perhaps you’ve noticed this when looking at AppleScript error messages when you get something like “circle 1 of document 1 of application Sketch” as an object’s identifier. Well, Core Data objects belong to a Managed Object Context, not a document, and while they are commonly a one-to-one relationship, there’s nothing saying it has to be that way. Similarly, objects have no intrinsic understanding of what document they’re in, so it’s hard to make an object specifier when you don’t know your parent.

But, it’s a solvable puzzle. You can ask NSApp for the list of documents and then compare each one’s MOC to your own until you find a match. Yes, it’s kludgy, but it’s fast (until you open 10K documents) and accurate (unless you share a MOC between documents). Here’s how you do it:

 – (NSScriptObjectSpecifier*) objectSpecifier

{
	NSEnumerator *enu = [[NSApp orderedDocuments] objectEnumerator];
	NSPersistentDocument *myDocument;


	
	while (myDocument = [enu nextObject])
		if ([myDocument managedObjectContext] == [self managedObjectContext])
			break;

	
	NSScriptObjectSpecifier *containerRef = [myDocument objectSpecifier];
	NSUniqueIDSpecifier *specifier = [NSUniqueIDSpecifier allocWithZone:[self zone]];
	[specifier initWithContainerClassDescription:[containerRef keyClassDescription]
				  containerSpecifier:containerRef
						 key:@“notes”
					    uniqueID:[self identifier]];

	
	return [specifier autorelease];

}

You may have noticed something there about the key argument being @“notes” when we don’t have anything called “notes” yet. Well, that argument is the method on the container that returns the list of this kind of object. It doesn’t exist yet, so we’ll make it.

Go to your document and create a method that returns a list of every note. It should try and ensure that there is a semi-reliable order to the array as well as Cocoa Scripting will be using the array to answer “the second note of the first document” specifiers for you. Luckily, we have an NSArrayController handy that is already maintaining an ordered, or arranged, list. Setup a connection between the document and the array controller in the document’s NIB and then add the following:

 – (NSArray*) notes

{
	return [noteController arrangedObjects];

}


	
- (void) setNotes: (NSArray*) newValue

{
	return; //no, not yours

}

We’re doing read-only, so I filled in the other method for you as a reminder. You don’t need to include it if you don’t want to. You’ll see later why this specific item is problematic in Core Data.

So, our document can give us a list of notes and our notes can identify themselves. Are we done? Pretty much. All that’s left is to tell Cocoa Scripting about our data and turn on OSA Scripting support for the application and then we’re good to go.

Creating the Scripting Definition

You could do this by hand, but I’m not going to. I use SDEF Editor to create my SDEF files. Get it, open it, and under the File → Open Standard Suite menu pick Skeleton. This is where we start.

The Skeleton option gives you the basic events suites for a document-based application. What we need to do now is add in our data.

1. Click on “My Terminology” and give it a better name.
2. In the Suites area to the right, click on the plus and create a new suite.
3. Name it something relevant and give it a unique four-letter code with at least one upper-case letter.
4. Click on Classes.
5. Add a class and call it “note” with a plural of “notes”, a superclass of “item”, a unique four-letter code (“Note” works), and the name of your Core Data entity for the Cocoa class (“note”).
6. Click on Properties and add the following properties (note that ‘ID ‘ has two important spaces after it):

Name	Code	Type	Description	Cocoa Class	Access
name	pnam	text	The name of the note.	name	Read/Write
id	ID	text	The ID of the note.	id	Read Only
note text	Ntxt	text	The text of the note.	content	Read/Write

Now that you’ve made the class, go into Standard Suite → Classes → document and then click on Elements. Add an element “note” that is Read Only with the Cocoa key “notes”. This is the array we made in the document class earlier.

Now save this in the same folder as the project and give it a very simple name as you’re adding it to the Info.plist file in the next step. Add this file to your Xcode project so that it gets copied into the bundle.

Enabling Scripting

You’re almost done. The last step is to tell Cocoa Scripting that you want to opt-in and where to locate your SDEF file. The following two keys should go somewhere in your Info.plist file:

<key>NSAppleScriptEnabled</key>
<string>YES</string>
<key>OSAScriptingDefinition</key>
<string>YOUR-NAME.sdef</string>

Now, build and run. Then open Script Editor.

Be sure and add the id property here. Because we’re using a unique ID specifier, Cocoa Scripting will use this property when doing a search for this object in the future. If it doesn’t exist, you’ll not be able to set this object to a variable and get information out of it without a vague -1700 error about not being able to get the data into the expected type (a coercion error). Then you’ll second-guess all of your code for a while, poking at it randomly only to post to the AppleScript Implementors list and have someone come back five minutes later with the answer when you’ve wasted several hours making fruitless changes because the error message was so damned useless. Or something like that. Bunny ears, leg to the north, moving on.

Testing It

Okay, you have model objects that can be identified, a document that can list them, and a Scripting Definition that tells the world about them. You’re set. Now do something like the following:

tell application "CD-AS Test"
	tell the first document
		set theNote to the first note
		set theContent to the properties of theNote
	end tell
end tell

You should get back something like the following (the exact note may differ):

{id:"x-coredata:///Note/t304A2D28-6641-4EB4-94A8-7A9993966108", name:"Note 4", class:note, note text:"Content 4"}

Now, you have limited read and write ability here. You can set name and note text without issue because these are strings. If you have numbers or other simple data types, you could set them here as well.

However, you cannot set the ID of the items, as those are determined by Core Data. You also cannot create objects as to create a Core Data object you have to tell it which managed object context it’s a part of, and AppleScript cannot do that. You cannot delete objects, either, as that normally means sending them a release call, but doing so to a CD object will not remove it from the store, and will imbalance its retain count in the process. You cannot, thus, use this solution to import or alter data en masse in its current form. This is also why you canot do “set the notes of the front document” — if you tried, you’d be changing the managed object context through the array controller, which doesn’t work so well when you can’t add or remove objects cleanly.

That said, it’s a good solution for getting data out of a program, and since it takes minimal effort to accomplish, it’s a nice and quick feature to add to make folks happy.