| Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision |
| dev:translators:scaffold [2018/02/08 07:02] – Update to Zotero 5.0 zuphilip | dev:translators:scaffold [2022/04/15 15:32] – Update for overhauled Scaffold abejellinek |
|---|
| <html><p id="zotero-5-update-warning" style="color: red; font-weight: bold">We’re | |
| in the process of updating the documentation for | |
| <a href="https://www.zotero.org/blog/zotero-5-0">Zotero 5.0</a>. Some documentation | |
| may be outdated in the meantime. Thanks for your understanding.</p></html> | |
| |
| |
| ====== Scaffold - an IDE for Zotero translators ====== | ====== Scaffold - an IDE for Zotero translators ====== |
| |
| Scaffold supports editing and testing web translators and import translators. Search and export translators can not yet be tested using the IDE. | Scaffold supports editing and testing web translators and import translators. Search and export translators can not yet be tested using the IDE. |
| |
| Scaffold 3 includes support for the [[dev:translators:testing|automated translator testing]] system that was introduced in Zotero 2.1.9, as well as for specifying [[dev:translators:connectors|connector compatibility]]. Documentation for these features is not yet available. | |
| |
| ===== Installation ===== | |
| |
| Scaffold does run within Zotero 5.0 as an [[:plugins|plugin]], which is installed by the following steps: | ===== Interface ===== |
| |
| * Download the XPI file of the [[https://github.com/zotero/scaffold/releases/latest|latest release of Scaffold]] | Scaffold is available via Tools → Developer → Translator Editor in Zotero. |
| * Open Zotero | |
| * Tools -> Add-ons -> (gear wheel) -> Install Add-on From File | |
| |
| Previously to Zotero Version 5.0, Scaffold was a Firefox Plugin. | When you first open Scaffold, you'll need to select your translator development directory. In most cases, this should be a git clone of the [[https://github.com/zotero/translators|Zotero translators repository]] on GitHub. |
| |
| | After selecting your translator directory, the main Scaffold window will open: |
| |
| ===== Interface ===== | {{:dev:translators:scaffold_new_small.png?750&nocache&nolink|}} |
| | |
| After installation, the "Tools" menu in Firefox should contain a "Scaffold" item. (If you don't have a Tools menu, see the Firefox instructions on how to [[https://support.mozilla.org/en-US/kb/what-happened-to-the-file-edit-and-view-menus|show the Menu Bar again]].) | |
| | |
| Selecting the Tools menu's "Scaffold" item opens the main Scaffold window: | |
| | |
| {{:dev:scaffold2.0-metadata.png?640&nocache&nolink|}} | |
| |
| ==== Top buttons ==== | ==== Top buttons ==== |
| Saves the translator you are currently working on. Provide a unique label and translator ID for your translator if you don't want to overwrite an existing translator. New translator IDs can be automatically generated via the "Generate" button. | Saves the translator you are currently working on. Provide a unique label and translator ID for your translator if you don't want to overwrite an existing translator. New translator IDs can be automatically generated via the "Generate" button. |
| |
| {{:dev:detectweb.png?nocache&nolink|}} **Run detectWeb** \\ | {{:dev:translators:savetozotero.png?16&nocache&nolink|}} **Save to Zotero** \\ |
| Saves and runs the ''detectWeb'' function of the translator code on the site loaded in the most recently selected tab. | Saves the translator you are currently working on and writes it to the "translators" subdirectory of the Zotero data directory, making it available to the client and Zotero Connector. (To use it in the Connector, open the Connector preferences to the Advanced tab and click Reset Translators.) |
| | |
| | {{:dev:translators:detectweb.png?16&nocache&nolink|}} **Run detect*** \\ |
| | Saves and runs the appropriate ''detect'' function: |
| | * If it's a web translator and a page is loaded in the Browser tab: ''detectWeb'' |
| | * If it's an import translator and data has been entered in the Test Data tab: ''detectImport'' |
| | * If it's a search translator and a JSON search object has been entered in the Test Data tab: ''detectSearch'' |
| | |
| | {{:dev:translators:doweb.png?16&nocache&nolink|}} **Run do*** \\ |
| | Saves and runs the appropriate ''do'' function of the translator code. Runs the corresponding ''do'' functions for the above situations, plus: |
| | * If it's an export translator and an item is selected in the main Zotero window: ''doExport'' |
| |
| {{:dev:doweb.png?nocache&nolink|}} **Run doWeb** \\ | |
| Saves and runs the ''doWeb'' function of the translator code on the site loaded in the most recently selected tab. | |
| |
| ==== Tabs ==== | ==== Tabs ==== |
| **Metadata** \\ Shows the translator metadata. Translator IDs can be generated via the "Generate" button. The target regular expression can be tested with the "Test Regex" button. | **Metadata** \\ Shows the translator metadata. Translator IDs can be generated via the "Generate" button. The target regular expression can be tested with the "Test Regex" button. |
| |
| **Code** \\ The text box in this tab contains the translator's JavaScript code: | **Code** \\ The text box in this tab contains the translator's JavaScript code. The editor supports syntax highlighting, folding of code parts, search and replace, basic type inference, code suggestions, Zotero-specific hints when hovering over an item type or translator UUID string, and more. |
| | |
| | **Tests**\\ This tab contains the list of tests saved in the translator, as well as the raw JSON and expected output for each one. You can run or update tests from here. Create tests from the corresponding tab for the type of test you want to create (Browser or Test Data). |
| | |
| | **Test Data** \\ Input data for import and search translators. |
| |
| {{:dev:scaffold2.0-code.png?640&nocache&nolink|}} | **Browser**\\ View sites and test detection and data extraction. |
| |
| ==== Debug Output ==== | ==== Debug Output ==== |
| If running ''detectWeb'' or ''doWeb'' results in an error, the debug window will show an error message. For debugging, additional debug output can be added to the code by adding ''Zotero.debug(string);'' statements. | If running ''detectWeb'' or ''doWeb'' results in an error, the debug window will show an error message. For debugging, additional debug output can be added to the code by adding ''Zotero.debug(string);'' statements. |
| |
| ===== Import Translators ===== | ===== Import, Export, and Search Translators ===== |
| Starting with version 2.1.2, Scaffold can be used to test import translators. To do so, enter the test import data in the "Import" tab and use the "Run detectImport" and "Run doImport" buttons to test the translator against the data. The output will be displayed in the right-hand pane as with web translators. | Starting with version 6.0, Scaffold can be used to test import, export, and search translators. To test an import or search translator, enter the test data in the "Test Data" tab and use the "Run detect*" and "Run *" buttons to test the translator against the data. The output will be displayed in the right-hand pane as with web translators. For export translators, select an item in the main Zotero window to use it for testing. |
| |
| In the translator load window, import translators are arranged in alphabetical order at the bottom of the list. | In the translator load window, import translators are arranged in alphabetical order at the bottom of the list. |
| |
| **Note:** The screenshots on this page do not reflect the changes made in Scaffold 2.1.2 to add support for import translators. | |
| |
| ===== Scaffold Troubleshooting ===== | ===== Scaffold Troubleshooting ===== |
| * **Why does my translator work in Scaffold but not when I click on the address bar icon in my browser?** | * **Why does my translator work in Scaffold but not when I click on the toolbar icon in my browser?** |
| Scaffold runs the functions ''detectWeb'' and ''doWeb'' against the active document in the top Firefox window. Outside of Scaffold, clicking the address bar icon runs the first web translator with a matching ''target'' regular expression that returns a non-false value from the function ''detectWeb'', when run on that document and URL. | Scaffold runs the functions ''detectWeb'' and ''doWeb'' against the active document in the top browser window. Outside of Scaffold, clicking the toolbar icon runs the first web translator with a matching ''target'' regular expression that returns a non-false value from the function ''detectWeb'', when run on that document and URL. |
| |
| This can differ from the active document in Firefox when the ''target'' expression or ''detectWeb'' conditions are too lax, which can allow embedded documents, such as IFRAMES used for advertising or sharing panes, to be detected as content pages. To see if this is what is happening, look at the debug output for a save attempt from Firefox proper and check the URL that is being processed. | This can differ from the active document in Firefox when the ''target'' expression or ''detectWeb'' conditions are too lax, which can allow embedded documents, such as ''iframe''s used for advertising or sharing panes, to be detected as content pages. To see if this is what is happening, look at the debug output for a save attempt from Firefox proper and check the URL that is being processed. |
| |
| * **Why won't my attachments save?** | * **Why won't my attachments save?** |
| ====== Further Reading ====== | ====== Further Reading ====== |
| |
| More detailed instructions are available at [[https://www.mediawiki.org/wiki/Citoid/Creating_Zotero_translators#For_translation-server_side_development |MediaWiki]]. See [[https://www.mediawiki.org/wiki/Citoid/Creating_Zotero_translators#For_development_through_IDE|For development through IDE]] | More detailed instructions are available at [[https://www.mediawiki.org/wiki/Citoid/Creating_Zotero_translators|MediaWiki]]. These instructions may be slightly out of date. |
| and [[https://www.mediawiki.org/wiki/Citoid/Creating_Zotero_translators#Run_on_Scaffold|Run on Scaffold]]. | |
Upgrade Storage