Differences
This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
dev:translator_development_outside_scaffold [2010/07/23 19:05] – created with initial TOC tomrochewiki | dev:translator_development_outside_scaffold [2017/11/12 19:53] (current) – external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | < | ||
+ | in the process of updating the documentation for | ||
+ | <a href=" | ||
+ | may be outdated in the meantime. Thanks for your understanding.</ | ||
+ | |||
+ | |||
===== Overview ===== | ===== Overview ===== | ||
- | In Zotero >= 2.0, translators are just [[http:// | + | In Zotero >= 2.0, translators are just [[wp>Javascript|javascript]] files. While [[http:// |
- find or create a Zotero development environment | - find or create a Zotero development environment | ||
Line 10: | Line 16: | ||
===== Find or create a Zotero development environment ===== | ===== Find or create a Zotero development environment ===== | ||
+ | |||
+ | One develops a translator to run on/against a given version of Zotero, which runs on/against a given version of Firefox. The easiest way to do this is just to use the current version of Zotero that is running in your current [[http:// | ||
+ | |||
+ | While convenient, using one's current Zotero | ||
+ | * runs the risk of corrupting one's current Zotero data, i.e. one's saved citations. | ||
+ | * does not allow one to develop against another version of Firefox or Zotero. | ||
+ | |||
+ | To create a separate Zotero development environment, | ||
+ | |||
+ | - Use Firefox' | ||
+ | - install the desired version of Zotero into your Firefox profile. One can install either | ||
+ | * [[/ | ||
+ | * [[/ | ||
+ | * [[dev/ | ||
===== Find or create a translator development environment ===== | ===== Find or create a translator development environment ===== | ||
+ | |||
+ | When developing directly against the filesystem, one's translator development environment is | ||
+ | * one's collection of one or more translator files | ||
+ | * the tools one uses to work on them | ||
+ | |||
+ | ==== Translator files ==== | ||
+ | |||
+ | === Translator file location === | ||
+ | |||
+ | Zotero installs its translators and related code as files in the subdirectory '' | ||
+ | * if the path to your Firefox profile=< | ||
+ | * if the path to your Zotero=< | ||
+ | |||
+ | TODO: how to get alternate/ | ||
+ | |||
+ | === Translator file structure === | ||
+ | |||
+ | At the highest level, a Zotero translator (for versions >= 2.0) consists of | ||
+ | * a single [[translators_reference_guide# | ||
+ | * non-metadata code, consisting of | ||
+ | * a '' | ||
+ | * a '' | ||
+ | |||
+ | ==== Translator development tools ==== | ||
+ | |||
+ | TODO: | ||
+ | * Zotero-enabled tools | ||
+ | * Zotero | ||
+ | * Javascript-enabled tools | ||
+ | * XPath tools | ||
===== Create or modify a translator file ===== | ===== Create or modify a translator file ===== | ||
+ | |||
+ | One can generate a completely new translator file using Scaffold 2.0. | ||
+ | - Start Scaffold. | ||
+ | - In tab=Metadata, | ||
+ | - In tab=Code, enter a '' | ||
+ | return " | ||
+ | } | ||
+ | </ | ||
+ | - Click on icon=Save (second from upper left). | ||
+ | - Check your translator filespace: you should have a new file with name based on field='' | ||
+ | - Close Scaffold. You may do all subsequent work directly on the new file. | ||
+ | |||
+ | However it is usually easier to create a new translator by copy/ | ||
+ | - working directly on an existing translator file (e.g. to fix a bug or add an feature) without modifying the '' | ||
+ | - " | ||
+ | - in the metadata block, | ||
+ | * create a new '' | ||
+ | * make the value of the '' | ||
+ | - in the code section, clear out any undesired contents from the '' | ||
+ | - somewhat " | ||
+ | - Find an existing translator with functionality that resembles what you want. | ||
+ | - Copy that to a new file in your translator filespace. | ||
+ | - Open the new file and | ||
+ | - change the metadata field='' | ||
+ | - assign a new value to field='' | ||
+ | - change the '' | ||
===== Edit, run, test, debug ===== | ===== Edit, run, test, debug ===== | ||
+ | |||
+ | ==== Enable debugging output ==== | ||
+ | |||
+ | One must | ||
+ | * configure Firefox to write Zotero debugging output to a [[wp> | ||
+ | * start Firefox via command-line from a terminal emulator (i.e. not via an icon) | ||
+ | before one can see output from, e.g., Zotero.debug() calls. See detailed instructions for [[http:// | ||
+ | |||
+ | ==== Running a modified translator ==== | ||
+ | |||
+ | Zotero does not currently sense changes to a translator file after it has been loaded. The actions required to reload a modified translator depend on what has been modified: metadata or other code. | ||
+ | |||
+ | === Running a translator after modifying metadata === | ||
+ | |||
+ | If you have made changes to the metadata block of your translator, you must restart the Firefox profile containing your modified translator. | ||
+ | |||
+ | === Running a translator after modifying non-metadata code === | ||
+ | |||
+ | If you have made changes to code outside the metadata block of your translator, you need only restart the page on which you want to run the translator. | ||
===== Contribute your translator ===== | ===== Contribute your translator ===== | ||
+ | |||
+ | Once your translator works on a subset of the sites on which you believe it should work, please [[translator_overview# | ||