| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| dev:client_coding:changes_in_zotero_3.0 [2011/08/21 04:47] – simon | dev:client_coding:changes_in_zotero_3.0 [2017/11/27 05:13] (current) – Remove Zotero 5 warning bwiernik |
|---|
| |
| ==== Zotero.done() and Zotero.wait() are deprecated ==== | ==== Zotero.done() and Zotero.wait() are deprecated ==== |
| * Calling Zotero.done() and Zotero.wait() during translation is no longer necessary. Zotero.done() is still used to indicate item type in translators that implement asynchronous detection (currently only unAPI). | Calling ''Zotero.done()'' and ''Zotero.wait()'' during translation is no longer necessary. ''Zotero.done()'' is still used to indicate item type in translators that implement asynchronous detection (currently only unAPI). |
| |
| ==== Zotero connectors require changes to translator code ==== | ==== Customizable attachment export ==== |
| Zotero Everywhere will soon allow translators to operate outside of Firefox/XULRunner. Legacy translators can still run inside Zotero Standalone, but will require that Zotero Standalone is running to operate. This will require the following code changes: | When the ''exportFileData'' option is specified and selected, attachments are no longer saved automatically. Instead, you should call the ''attachment.saveItem(relativePath, overwriteExisting)'' method to save attachments. ''relativePath'' is the path to the attachment relative to the folder in which the metadata file resides; if intermediate directories do not exist, they are created automatically. ''overwriteExisting'' determines whether existing attachments are automatically overwritten; if false, a ''ERROR_FILE_EXISTS'' error will be thrown. |
| |
| * Firefox-specific JavaScript, with the exception of "for each", must be avoided. This includes | ==== ZU.removeDiacritics() ==== |
| | |
| | ''Zotero.Utilities.removeDiacritics(str, lowercaseOnly)'' removes diacritics from a string, returning the result. The second argument is an optimization that specifies that only lowercase diacritics should be replaced. |
| | ==== ZoteroItemUpdated event ==== |
| | Sites can now fire the ''ZoteroItemUpdated'' event to force Zotero to re-run detection after new data is loaded asynchronously ([[:dev:exposing_metadata#using_an_open_standard_for_exposing_metadata|example code]]). |
| | |
| | ==== Modifying translators to run in the Zotero Connectors ==== |
| | Zotero Connectors now allow translators to operate outside of Firefox/XULRunner. Legacy translators can still run inside Zotero Standalone, but will require that Zotero Standalone is running to operate. In order to run in the Zotero Connectors, translators must conform to the following rules. |
| | |
| | === No Firefox-specific JavaScript === |
| | Firefox-specific JavaScript, with the exception of "for each", must be avoided. This includes |
| * array comprehensions | * array comprehensions |
| * destructuring assignment | * destructuring assignment |
| * several other features | * several other features |
| |
| * E4X functionality is not available. As of Zotero 2.1b6, Zotero also offers DOM XML interfaces to translators. Current trunk builds offer cross-browser utility functions for working with XPaths detailed above, which greatly simplify migration away from E4X. | === E4X unavailable === |
| | E4X functionality is not available. As of Zotero 2.1b6, Zotero also offers DOM XML interfaces to translators. Current trunk builds offer cross-browser utility functions for working with XPaths detailed above, which greatly simplify migration away from E4X. |
| * Zotero.Utilities.retrieveDocument() and Zotero.Utilities.retrieveSource() should be avoided. Zotero.Utilities.retrieveDocument() will throw an error outside of Firefox, whereas Zotero.Utilities.retrieveSource() will freeze the main thread and will not work across domains. Code should be rewritten to use Zotero.Utilities.processDocuments(), Zotero.Utilities.HTTP.doGet(), or Zotero.Utilities.HTTP.doPost(), which remain available in all environments. | |
| |
| * Translate#getTranslatorObject() should now be called with a callback function as an argument, which will receive the translator object when it is available. This is backwards compatible with Zotero 2.1b6 and later. | === retrieveSource() and retrieveDocument() are unavailable === |
| * In Chrome and Safari, the "exports" object is exposed to other translators, rather than the entire translator sandbox. Any variables or functions that need to be accessible to other translators should be properties or methods of this object. In Zotero 2.1.9 and later, Translate#getTranslatorObject() will always return the "exports" object if it has properties. | Zotero.Utilities.retrieveDocument() and Zotero.Utilities.retrieveSource() should be avoided. Zotero.Utilities.retrieveDocument() will throw an error outside of Firefox, whereas Zotero.Utilities.retrieveSource() will freeze the main thread and will not work across domains. Code should be rewritten to use Zotero.Utilities.processDocuments(), Zotero.Utilities.HTTP.doGet(), or Zotero.Utilities.HTTP.doPost(), which remain available in all environments. |
| |
| * Translators should not expect a return value from Translate#getTranslators(). Instead, they should register a "translators" handler, which will receive the list of translators as the second argument. This is backwards compatible with Zotero 1.0 and later. | === getTranslatorObject() must be called with a callback === |
| | Translate#getTranslatorObject() should now be called with a callback function as an argument, which will receive the translator object when it is available. This is backwards compatible with Zotero 2.1b6 and later. |
| |
| * Zotero.selectItems() should now be called with a callback function as an argument, which will receive the list of selected items when it is available. Translators may still use Zotero.selectItems() synchronously, but this will require that the first part of the translator be executed twice. This is backwards compatible with Zotero 2.1b6 and later. | === Translators that export objects via getTranslatorObject() must define exported objects explicitly === |
| | In Chrome and Safari, the "exports" object is exposed to other translators, rather than the entire translator sandbox. Any variables or functions that need to be accessible to other translators should be properties or methods of this object. In Zotero 2.1.9 and later, Translate#getTranslatorObject() will always return the "exports" object if it has properties. |
| |
| ===== Making add-ons for Zotero Standalone ===== | === getTranslators() does not return === |
| | Translators should not expect a return value from Translate#getTranslators(). Instead, they should register a "translators" handler, which will receive the list of translators as the second argument. This is backwards compatible with Zotero 1.0 and later. |
| |
| It is possible to create add-ons for Zotero Standalone just as one would create add-ons for Firefox. To do so, simply add the following lines to install.rdf: | === selectItems() should be called with a callback === |
| | Zotero.selectItems() should now be called with a callback function as an argument, which will receive the list of selected items when it is available. Translators may still use Zotero.selectItems() synchronously, but this will require that the first part of the translator be executed twice. This is backwards compatible with Zotero 2.1b6 and later. |
| | |
| | ===== Translator testing framework ===== |
| | |
| | Zotero 3.0 contains a translator testing framework, used by Scaffold 3.0. You can also run available translator tests in batch mode by accessing the translator tester page. In Firefox, this page is available in the standard extension at: |
| | |
| | <code>chrome://zotero/content/tools/testTranslators/testTranslators.html</code> |
| | |
| | In Chrome and Safari, the translator tester is accessible from the Advanced pane of the preferences in [[/support/dev_builds#connector_debug_builds|connector debug builds]]. |
| | |
| | ===== Add-on support in Zotero Standalone ===== |
| | |
| | It is possible to create add-ons for Zotero Standalone just as one would create add-ons for Firefox. To do so, create a Firefox extension, but add the following lines to install.rdf: |
| |
| <code xml> | <code xml> |
| </code> | </code> |
| |
| where minVersion is the lowest Zotero Standalone version you have tested with, and maxVersion is the maximum version you can reasonably expect your add-on to work with. For add-ons that overlay [[changes_in_zotero_2.1#changes_to_interface-related_code|zoteroPane.xul]], this addition should be sufficient, and the same XPI should work in both Firefox and Zotero Standalone. | where minVersion is the lowest Zotero Standalone version you have tested with, and maxVersion is the maximum version you can reasonably expect your add-on to work with. For add-ons that overlay [[changes_in_zotero_2.1#changes_to_interface-related_code|zoteroPane.xul]], this addition should be sufficient, and the same XPI should work in both Firefox and Zotero Standalone. If your add-on overlays browser.xul, you should change it to overlay zoteroPane.xul. |
| | |
| | Calls to ''window.loadURI()'' will not work in Zotero Standalone. However, you can use ''ZoteroPane.loadURI()'' to load a URI in the default browser, or ''ZoteroStandalone.openInViewer()'' to open a page in Zotero Standalone. |
| |
| To install an add-on in Zotero Standalone, go to Tools->Add-ons and choose "Install Add-on From File..." from the cog menu. | To install an add-on in Zotero Standalone, go to Tools->Add-ons and choose "Install Add-on From File..." from the cog menu. |
| | ===== Miscellaneous changes ===== |
| | |
| | ==== Zotero.Translate itemSaving handler ==== |
| | Zotero.Translate now fires both ''itemSaving'' and ''itemDone'' handlers. |
| | |
| | The ''itemSaving'' handler is called as soon as the translator returns an item, but before it's saved to the database. It is passed the item object returned by the translator as the second argument. |
| | |
| | The ''itemDone'' handler is called after the item is saved. When not operating in connector mode, it is passed the DB item as its second argument and the item object returned by the translator as its third. When operating in connector mode, or when ''false'' is passed to ''Zotero.Translate#translate'' is passed the item object returned by the translator as both arguments. |
| | |
| | ==== getNotes(), getAttachments, and getTags() return empty arrays ==== |
| | Zotero.Item.getNotes(), Zotero.Item.getAttachments(), and Zotero.Item.getTags() now return empty arrays rather than FALSE if no matches |
Upgrade Storage