home *** CD-ROM | disk | FTP | other *** search
// // PapersImporterPluginProtocol.h // // Created by Alexander Griekspoor on Fri Jan 23 2007. // Copyright (c) 2007 Mekentosj.com. All rights reserved. // // For use outside of the Papers application structure, please contact // feedback@mekentosj.com // DO NOT REDISTRIBUTE WITHOUT ALL THE FILES THAT ARE CONTAINED IN THE PACKAGE THAT INCLUDED THIS FILE #import <Cocoa/Cocoa.h> ///////////////////////////////////////////////////////////// /* Importing records Papers allows you through this protocol to write your own importer plugins. These can not only be used to import files but any kind of data from any source. It's important to note that the plugin's method performImportWithURLs: runs in its own thread, although you normally would not have to worry about that, keep in mind that if you do fancy stuff you use "performMethodOnMainThread: to prevent trouble. The plugin signals it's progress to the delegate using a number of delegate methods. Make sure you ALWAYS call the delegate methods to signal your progress. A normal cycle of the plugin would be: Delegate -> Plugin - (BOOL) readyToPerformImport; // Is the plugin Ready, if not importPreparationError is retrieved. Delegate -> Plugin - (void) performImportWithURLs: (NSArray *)urls; // Delegate provides plugin with urls, initiates import. Delegate <- Plugin - (void)didBeginImport:(id)sender; // Plugin informs delegate that it has started. Delegate <- Plugin - (void)didImportObject:(NSDictionary *)dict; // Plugin hands over found paper to delegate (optionally repeated). Delegate <- Plugin - (void)didEndImport:(id)sender; // Plugin signals it's done. Delegate -> Plugin - (BOOL) successfulCompletion; // Delegate asks plugin if success, if not importCompletionError is retrieved. Delegate -> Plugin - (void) performCleanup; // Allows the plugin to cleanup and reset for next import. The structure of the dictionary containing imported objects is as follows. Note that you are encouraged to fill as many of these fields as you can. You can also provide other fields if you wish but these will be ignored within Papers in the current version. Potential other programs that also use these plugins might use this info though. NOTE: you do not have to list all fields except those marked as obligatory Note that at the root of the dictionary you can provide one or more arrays named: - papers, an array containing dictionaries representing a paper. - authors, an array containing dictionaries representing an author. - journals, an array containing dictionaries representing a journal. - keywords, an array containing dictionaries representing a keyword. - publicationTypes, an array containing dictionaries representing a publication type. Each can only occur once (!) and contains an array of the corresponding model dictionaries below. Usually you will only return Papers, but in case you would like to import a list of journals or authors irrespective outside the context of a paper this is the way to do it. NOTE: IF YOU ADD AN AUTHOR, JOURNAL, KEYWORD, OR PUBLICATION TYPE TO A PAPER, DON'T ADD IT SEPARATELY AGAIN IN THE AUTHORS, JOURNALS, KEYWORDS, or PUBLICATION TYPES ARRAYS!! ONLY USE THE OTHER CATEGORIES IF YOU DON'T IMPORT PAPERS OR IF YOU ADD EXTRA MODEL OBJECTS NOT ASSOCIATED TO THE PAPERS YOU IMPORTED. Below follows an example for each category Unless otherwise noted NSStrings are expected for all field AUTHORS - correspondence - email - firstName - homepage - initials - lastName - required - mugshot (NSImage) - nickName - notes Example: <key>authors</key> <array> <dict> <key>correspondence</key> <string>The European Bioinformatics Institute</string> <key>email</key> <string>mek@mekentosj.com</string> <key>firstName</key> <string>Alexander</string> <key>homepage</key> <string>http://mekentosj.com</string> <key>initials</key> <string>AC</string> <key>lastName</key> <string>Griekspoor</string> <key>mugshot</key> NSImage object <key>nickName</key> <string>Mek</string> <key>notes</key> <string>These are example notes</string> </dict> <dict> .. next author .. </dict> </array> JOURNALS - abbreviation - archives - authorGuidelines - cover (NSImage) - currentissue - etoc - homepage - impactFactor (NSNumber - Float) - issn - language - name - required - nlmID - notes - openAccess (NSNumber - BOOL) - publisher - startYear (NSNumber - Int) - summary Example: <key>journals</key> <array> <dict> <key>abbreviation</key> <string>PLoS Biol.</string> <key>archives</key> <string>http://biology.plosjournals.org/perlserv/?request=get-archive&issn=1545-7885</string> <key>authorGuidelines</key> <string>http://journals.plos.org/plosbiology/guidelines.php</string> <key>cover</key> NSImage object <key>currentissue</key> <string>Vol. 4(12) December 2006</string> <key>etoc</key> <string>http://biology.plosjournals.org/perlserv/?request=get-toc&issn=1545-7885</string> <key>homepage</key> <string>http://biology.plosjournals.org/</string> <key>impactFactor</key> <real>14.2</real> <key>issn</key> <string>1545-7885</string> <key>language</key> <string>eng</string> <key>name</key> <string>PLoS Biology</string> <key>nlmID</key> <string>101183755</string> <key>notes</key> <string>More info here...</string> <key>openAccess</key> <true/> <key>publisher</key> <string>Public Library of Science</string> <key>startYear</key> <integer>2003</integer> <key>summary</key> <string>PLoS Biology is an open-access, peer-reviewed general biology journal published by the Public Library of Science (PLoS), a nonprofit organization of scientists and physicians committed to making the world's scientific and medical literature a public resource. New articles are published online weekly; issues are published monthly.</string> </dict> <dict> .. next journal .. </dict> </array> KEYWORDS - identifier - name - required - qualifier - type - subtype Example: <key>keywords</key> <array> <dict> <key>identifier</key> <string>an identifier</string> <key>name</key> <string>Breast Cancer</string> <key>qualifier</key> <string>a qualifier</string> <key>subtype</key> <string>Major Topic</string> <key>type</key> <string>MeSH Heading</string> </dict> <dict> .. next keyword .. </dict> </array> PUBLICATION TYPES - name - required Example: <key>publicationTypes</key> <array> <dict> <key>name</key> <string>Journal Article</string> </dict> <dict> .. next publication type .. </dict> </array> PAPERS -abstract -acceptedDate (NSDate) -affiliation -authors (NSArray of author dictionaries - see above) -category -doi -image (NSImage) -issue -journal (NSArray with a single journal dictionaries - see above) -keywords (NSArray of keywords dictionaries - see above) -label -language -notes -openAccess (NSNumber - BOOL) -pages -path (NOTE that providing a path to a pdf file will automatically invoke auto-archiving if enabled) -pii -pmid -publicationTypes (NSArray of publication type dictionaries - see above) -publishedDate (NSDate) -receivedDate (NSDate) -revisedDate (NSDate) -status -timesCited (NSNumber - Int) -title -url -volume -year (NSNumber - Int) Example: <key>Papers</key> <array> <dict> <key>abstract</key> <string>MicroRNAs (miRNAs) interact with target...</string> <key>acceptedDate</key> NSDate object <key>affiliation</key> <string>Computational Biology Center</string> <key>authors</key> ... HERE AN ARRAY OF AUTHOR DICTIONARIES LIKE ABOVE ... <array/> <key>category</key> <string>Journal Article</string> <key>doi</key> <string>10.1371/journal.pbio.0020363</string> <key>image</key> NSImage object <key>issue</key> <string>3</string> <key>journal</key> ... HERE AN ARRAY WITH A SINGLE JOURNAL DICTIONARY LIKE ABOVE ... <array/> <key>keywords</key> ... HERE AN ARRAY OF KEYWORD DICTIONARIES LIKE ABOVE ... <array/> <key>label</key> <string>Cell Biology</string> <key>language</key> <string>eng</string> <key>notes</key> <string>Here more info...</string> <key>openAccess</key> <true/> <key>pages</key> <string>e363</string> <key>path</key> <string>/Users/griek/Documents/Papers/1550875.pdf</string> <key>pii</key> <string>0020363</string> <key>pmid</key> <string>15502875</string> <key>publicationTypes</key> ... HERE AN ARRAY OF PUBLICATION TYPE DICTIONARIES LIKE ABOVE ... <array/> <key>publishedDate</key> NSDate object <key>receivedDate</key> NSDate object <key>revisedDate</key> NSDate object <key>status</key> <string>In press</string> <key>timesCited</key> <integer>12</integer> <key>title</key> <string>Human MicroRNA targets</string> <key>url</key> <string>http://biology.plosjournals.org/perlserv/?request=get-document&doi=10.1371/journal.pbio.0020363</string> <key>volume</key> <string>2</string> <key>year</key> <integer>2006</integer> </dict> </array> SEE THE COMPLETE EXAMPLE PLIST THAT CAME WITH THIS PACKAGE. NOTE THAT WE EXPECT THE ORIGINAL DICTIONARY, NOT A PLIST OR SERIALIZED DICTIONARY */ ///////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////// /* USING NSERRORS NSErrors are returned by two of the methods below in order to allow the main application to inform the user of problems that occur while trying to use the plugin. The domain should always be "Papers Importer Error" The user dictionary should have two keys: "title" and "description". By default, they will be used to create the text of an informative dialog as: "title: description" So design your messages accordingly. PLEASE LOCALIZE YOUR MESSAGES WITHIN YOUR PLUGIN Make sure the "title" and "description" keys are in an appropriate language by the time the application gets the NSError. This will allow the bundle to be entirely self-contained. Even if you don't know any other languages, provide the structure within your plugin to allow others to do the localization. */ ///////////////////////////////////////////////////////////// // THESE ARE METHODS THE PLUGIN DELEGATE IMPLEMENTS AND YOU SHOULD CALL @protocol PapersImporterPluginDelegate <NSObject> // Signal the delegate that you started the import process // Allows the delegate to prepare the interface before displaying new data - (void)didBeginImport:(id)sender; // Tell the delegate to create a new folder with name "name" // With level you indicate the hierarchy, use level 0 for "root" level // all objects you import after calling this method are added to the // last created Group - (void)shouldCreateGroupWithName: (NSString *)name level: (int)level; // Provide here an autoreleased dictionary containing the results from your import. The structure of what this // dictionary should look like is shown above. Papers will convert this dictionary in the corresponding model objects for you. // If you provide no or an empty dictionary Papers will warn the user no records were imported. // You can post the results one at the time or in batches or all at once. If you provide them all at once, return nil for // itemsToImport so that an indeterminate progressbar is shown. - (void)didImportObject:(NSDictionary *)dict; // Signal the delegate that you are done. The delegate will inform how things went so be sure to set any errors and be ready // to answer didCompleteSuccessfully. - (void)didEndImport:(id)sender; // Inform the delegate of a status change, use when statusString, importedItems or itemsToImport changes. // Status updates are automatically issued by calling any of the methods above - (void)updateStatus:(id)sender; // Ask the delegate for its internet connection status - (BOOL)isConnectedToInternet; @end // THESE ARE METHODS YOUR PLUGIN SHOULD IMPLEMENT @protocol PapersImporterPluginProtocol // gives you a handle to the delegate object to which you deliver results and notify progress (see above) // do not retain the delegate - (id)delegate; - (void)setDelegate: (id)del; // this should return an array of all menu items as strings. Menu titles should be as descriptive as possible, // so that we don't have naming collisions. - (NSArray *) menuTitles; // if your plugin works with files return YES, Papers will run the open panel for you (with the // indicated allowedFileTypes and accessoryView if required. // // NOTE: that your plugin can import anything you like and doesn't have to start with a file. // You can open a sheet, interact with a website, fetch data etc. Just return NO here in that case. - (BOOL) shouldShowOpenPanel; // if your plugin returns YES on the above method, you have to return the allowedFileTypes as well. - (NSArray *) allowedFileTypes; // indicate what can be selected. Return NO when you don't open a file. - (BOOL) canChooseFiles; - (BOOL) canChooseDirectories; - (BOOL) canChooseMultiple; // if you would like to customize the openpanel even further, set one up and return your own. // Otherwise return nil for the default one. - (NSOpenPanel *) openPanel; // if you would like to show options while the open panel is shown, return a custom view here and it will // be used as accessoryView. Otherwise return nil. - (NSView *) accessoryView; // Return YES if you need an active internet connection in order to import your objects. // If you return YES, Papers will check whether a connection is available. - (BOOL)requiresInternetConnection; // a method to make sure everything's set to go before starting, do some setup or tests here if necessary. // and a method to find out what the problems are if things aren't set. See above for usage of errorCodes. - (BOOL) readyToPerformImport; - (NSError *) importPreparationError; // Return YES if you support cancelling the current import session (strongly advised). - (BOOL)canCancelImport; // Return YES if imported results should be linked to existing objects as much as possible (like authors). Returning NO might // result in duplicates - (BOOL)shouldMerge; // Return YES if imported results should overwrite existing fields during a merge. For instance you are importing an author already // present in the library with a different email address. - (BOOL)shouldOverwrite; // this method is the main worker method and launches the import process, here you are handed over // the URLs that were selected in the open panel, this array can be empty or nil if you return NO // to shouldShowOpenPanel, in case you want to ignore this argument anyway. // NOTE that this method runs in a separate thread. Signal your progress to the delegate. - (void) performImportWithURLs: (NSArray *)urls; // informs us that we should stop importing. Since we're running in a thread we should check regularly // if we have been cancelled - (void) cancelImport; // return the number of items you found and are about to import. As long as this value is nil an indeterminate // progress bar is shown, the moment you return a non-nil value for both the progress will be shown to the user. // use in combination with the delegate method updateStatus: to push changes to the delegate and force an update. - (NSNumber *)itemsToImport; - (NSNumber *)importedItems; // return the current status of your plugin to inform the user. make sure these strings are localizable! // use in combination with the delegate method updateStatus: to push changes to the delegate and force an update. - (NSString *)statusString; // A method to check whether the import finished properly // and one to get at any errors that resulted. See above for usage of errorCodes. - (BOOL) successfulCompletion; - (NSError *) importCompletionError; // let the plugin get rid of any data that needs to be reset for a new import. - (void) performCleanup; @end 
