On 3/23/16 4:19 PM, jl wrote:
> Thanks for the update! Not sure how I will manage the transition for
> zotfile considering time constraints but I will see. Any easy way to
> get a list of methods that are now promise-based or have changed in
> significant ways?
No, sorry, we weren't quite as diligent as we might have been at keeping
track of the changes — the changes were just too extensive — though in
many cases we used different functions or had the old ones throw/warn
when passed outdated parameters. But a simple grep/ack -C 2 for the
function name will be enough to tell quickly in most cases — the ones
that return promises will generally now either be wrapped in
Zotero.Promise.coroutine() or say "@return {Promise}" on the comment
line above.
If we make additional function changes between now and 5.0 Final we'll
be sure to document them in the commits, so keep an eye on the commit log.
> As a rough rule, the data retrieval methods remain unchanged
> and writes are promise based?
Yes, though some of the auxiliary retrieval methods that are based on
SQL queries (e.g., Zotero.Item.prototype.getBestAttachments()) we
haven't yet deasyncified or can't be (e.g.,
Zotero.Search.prototype.search()), and file-based retrieval methods
generally are now promise-based or were replaced with async versions
(e.g., getFile -> getFilePathAsync(); a synchronous getFilePath() exists
but it doesn't do a file existence check, since that's an async op).
Various file methods also now work with regular string paths, following
Mozilla's OS.File approach, instead of nsIFiles.
> Here is a (probably incomplete) list of methods used in zotfile based
> on a quick regex search.
Some quick annotations off the top of my head:
> Zotero.Attachments.getFileBaseNameFromItem()
> Zotero.Attachments.getStorageDirectory()
Unchanged
> Zotero.Attachments.importFromFile()
> Zotero.Attachments.linkFromFile()
Return promises
> Zotero.Browser.createHiddenBrowser()
> Zotero.Browser.deleteHiddenBrowser()
Unchanged
> Zotero.Collections.get()
Unchanged, thanks to deasyncification
> Zotero.DB.beginTransaction()
> Zotero.DB.commitTransaction()
Replaced with promise-based executeTransaction(function* () { ... })
> Zotero.debug()
Unchanged
> Zotero.File.createDirectoryIfMissing()
Unchanged, but should probably return a promise
> Zotero.File.getExtension()
> Zotero.File.getValidFileName()
> Zotero.getStorageDirectory()
> Zotero.getZoteroDirectory()
Still return nsIFiles, but you can add .path to use with OS.Path.join()
instead of using nsIFile .append(). Going the other direction,
Zotero.File.pathToFile() will convert a path to an nsIFile. Many methods
now take either (e.g., Zotero.File.getContentsAsync()).
> Zotero.getString()
> Zotero.HTTP.doGet()
Use promise-based Zotero.HTTP.request() instead
> Zotero.Item()
> Zotero.Items.get()
> Zotero.ItemTypes.getLocalizedString()
> Zotero.ItemTypes.getName()
> Zotero.launchFile()
> Zotero.logError()
> Zotero.Notifier.registerObserver()
> Zotero.Notifier.unregisterObserver()
> Zotero.Prefs.get()
> Zotero.Search()
All unchanged. Note that you may see Zotero.Items.getAsync() and similar
in some places, but those just haven't been reverted since deasyncification.
> Zotero.Searches.getAll()
Returns a promise, but that should be deasyncified.
> Zotero.Sync.Storage.setSyncedHash()
> Zotero.Sync.Storage.setSyncState()
Replaced with attachmentSyncedHash and attachmentSyncState properties on
Zotero.Item.prototype, and require separate item save()/saveTx().
> Zotero.Tags.getID()
> Zotero.Tags.getName()
> Zotero.Utilities.htmlSpecialChars()
> Zotero.Utilities.levenshtein()
> Zotero.Utilities.removeDiacritics()
> Zotero.Utilities.text2html()
> Zotero.Utilities.trimInternal()
Unchanged
> ZoteroPane.getSelectedLibraryID()
> ZoteroPane.getSelectedCollection()
> ZoteroPane.getSelectedItems()
> ZoteroPane.getSelectedSavedSearch()
Unchanged
> ZoteroPane.onCollectionSelected()
> ZoteroPane.collectionsView.selectLibrary()
Return promises, for complicated reasons
> ZoteroPane.itemsView.selectItems()
> ZoteroPane.itemsView.saveSelection()
Unchanged