Creating Plug-ins

If you would like to create your own plug-ins, it helps if you know a bit about Cocoa already. But if you're a complete novice, don't let that deter you. There are some great online resources for Cocoa programmers - beginners and pros alike - such as CocoaDev, Cocoabuilder.com and Cocoa Dev Central.
Of course you may also use the Bruji forum to talk to other programmers.

Getting straight to the nitty-gritty: the plug-in has an informal protocol of the following four methods. Only one is mandatory, the others are optional.
If you'd like to get straight to programming, use the following xcode project file with a built example for you to add to.

Plug-in informal protocol

                @interface NSObject
                + (id)plugin;  //mandatory search functions
                - (void)searchFor:(NSDictionary *)searchDict sender:(id)sender;

                - (NSDictionary *)resultNumber:(int)number;
                - (NSArray *)resultsTitles;

                // Menu command functions

                - (NSArray *)menuCommandFor:(NSMutableArray *)entries;

                - (void)setImagePath:(NSString *)path;

                @end
            

What are those functions?

The first function is a plug-in initializer and should return self. This is the mandatory function, as it loads the plug-in. In most plug-ins the function will consist of a single line:

return [[[self alloc] init] autorelease];

searchFor: sender: implements the search plug-in. It receives a NSDictionary called info with the following entries, which you can use to lookup, for example, DVD information.
Keep in mind though that these entries are supplied by the user and might be empty strings. If you don't have the entries required to lookup information, tell the sender that there are zero results. The NSDictionary may also contain a single entry with key "Keyword" if your plug-in is used from the search window.

Name	Type
Keyword	NSString
Title	NSString
Director	NSString
UPC	NSString
Release	NSString
IMDB	NSString
Starring	NSString
Media	NSString
Keyword	NSString

When you have performed the search and have established the number of results, you let the sender know with:

- (void)searchReturnedNumberOfResults:(int)numberOfResults sender:(id)sender;

The number results is an int and sender should be self. In the provided example numberOfResults is the count of the array that holds the result titles.

- (NSArray *)resultsTitles; should return an NSArray containing NSStrings for the titles of all the results to present to the user in the results drawer for selection.

- (NSDictionary *)resultNumber:(int)number; should return an NSDictionary with the fields for the values you would like to supply for that particular result. The one different entry is "ImageLocation" which should be an NSString with a URL location of where to download the cover image from.


menuCommandFor: gets called when a user selects your plug-in menu command if there is one. The incoming NSArray called "entries" contains MOEntry that are NSManagedObjects of the selected movies. These are pointers to the direct information on the users database so take care when modifing them. Make modifications directly and do not return this array as it would duplicate the entries.

You may return a new NSArray of NSMutableDictionary to add entries to the selected collection, otherwise return nil and the main table wil reload to show the modifications.

- (NSString)coverImagePath; Will return the path of the image connected to a MOEntry passed in the array.

You are well on your way to creating a plug-in. All you need now is to name your search and/or menu command. In your info.plist file add two new entries with unique and descriptive names for your plug-in as this is what the user will see. Note: separate plug-ins with duplicate names will not be loaded.

        <key>PluginSearchName</key>

        <string>Your search Name hopefully with the site you search</string>

        <key>PluginMenuName</key>
        <string>Your menu command, do the following on selection</string>
    

Now you are done and can build your plug-in. If you do write your own plug-in, please consider sharing it with other Pedia users. You can send it to us and we'll put it up for download on our Extras page. Plug-ins may be freeware, donationware, shareware or commercial.