The Basics

Follow this guide to add the nudge:nudge Tagging Framework to your application.

Link the framework

Drag NNTagging.framework into the Linked Frameworks folder of your Xcode project and make sure to check the "Copy items into destination group's folder" box in the resulting sheet.

Deploy the framework

• Create a new Copy Files build phase (Project > New Build Phase) and select Frameworks for destination.
• Switch to the Project page (cmd-0), find your target in the files list, and reveal its contents by clicking the disclosure triangle next to it.
• Drag NNTagging.framework from the Linked Frameworks folder to the new Copy Files phase.

Next Steps

Create new tag

NNTag *newTag = [[NNTags sharedTags] tagForName:"newTagName" 
                                creationOptions:NNTagsCreationOptionFull];

New tags are automatically added to the tag database and are saved to the disk, you don't have to care about that. After the creation, tags can be accessed using

NNTag *oldTag = [[NNTags sharedTags] tagForName:"newTagName"];
//oldTag might be nil, if there is no such tag

Add tag to file

To add a tag to a file, use the NNFile class by initializing it from a file path given as NSString, then calling the

addTag:

method.

NSString *pathToFile = "/path/to/file";
NNFile *newFile = [NNFile fileWithPath:pathToFile];
[newFile addTag:newTag];

The NNFile will take care of writing the spotlight comment

Search for a tag

There are two ways to do this:

1. First, you need to create a query and set the tag to search for

   NNQuery *query = [[NNQuery alloc] init];
   NNSelectedTags *selectedTags = 
   	[[NNSelectedTags alloc] initWithTags:[NSArray arrayWithObjects:newTag,nil]];
   [query setTags:selectedTags];
   

   Then you should register for the NNQuery notifications and start the search

   [[NSNotificationCenter defaultCenter] addObserver:self 
       selector:@selector(queryNote:) 
       name:NNQueryDidFinishGatheringNotification object:query];
   [query startQuery];
   

   For other query notifications check the NNQuery API.

   As an alternative, you could simply use

   NSArray *results = [query executeSynchronousQuery];
   

   which will not post any progress notifications but return the results immediately. (This has the same implications as using [tag taggedObjects] - see below!)

   Once the results have been gathered, you can get to them using the following snippet.

   NSArray *results = [query results];
   

   The results are of the NNTaggableObject class.

2. This way is easier by far:

   NNTag *tag = [[NNTags sharedTags] tagForName:"tagName"]; 
   // tag may be nil, check for this in your code,
   // or use tagForName:creationOptions with NNTagsCreationOptionFull
   NSArray *taggableObjects = [tag taggedObjects];
   

The second way is of course easier to use, but has several disadvantages

• Search is executed synchronously in the thread calling the taggedObjects: method - this could lead to quite some interface blocking if called from main thread.
• You can not see intermediate results, as you can with NNQuery registering for the NNQueryGatheringProgressNotification.

We hope this gave you a quick grasp of what the framework does, there are a lot more classes and more functionality, though, so be sure to look at the API for the appropriate classes.