Differences

This shows you the differences between two versions of the page.

--- dev:translator_development_outside_scaffold [2010/07/24 15:36] – add debugging output, note on tools tomrochewiki
+++ dev:translator_development_outside_scaffold [2011/10/14 13:32] – [Find or create a Zotero development environment] rmzelle
@@ Line 1: / Line 1: @@
 ===== Overview =====
-In Zotero >= 2.0, translators are just [[http://en.wikipedia.org/wiki/Javascript|javascript]] files. While [[http://bitbucket.org/rmzelle/scaffold/downloads|Scaffold 2.0]] can [[how_to_write_a_zotero_translator_plusplus|ease translator development]], some prefer to work directly on the filesystem. To do this, one must
+In Zotero >= 2.0, translators are just [[wp>Javascript|javascript]] files. While [[http://bitbucket.org/rmzelle/scaffold/downloads|Scaffold 2.0]] can [[how_to_write_a_zotero_translator_plusplus|ease translator development]], some prefer to work directly on the filesystem. To do this, one should
   - find or create a Zotero development environment
@@ Line 21: / Line 21: @@
   - Use Firefox's [[http://kb.mozillazine.org/Profile_Manager|Profile Manager]] to [[http://support.mozilla.com/en-US/kb/managing+profiles|create a Firefox profile]]. (Remember below to [[http://kb.mozillazine.org/Starting_Firefox_or_Thunderbird_with_a_specified_profile|start Firefox using that profile]].) (Note that, by default, only one Firefox profile can run at any given time.)
   - install the desired version of Zotero into your Firefox profile. One can install either
-    * [[http://www.zotero.org/support/installation|the latest Zotero release]]
+    * [[/support/installation|the latest Zotero release]]
-    * [[http://www.zotero.org/support/dev/svn_and_trac_access#development_xpi|a development XPI]]
+    * [[/support/dev_builds|a development XPI]]
-    * [[http://www.zotero.org/support/dev/svn_and_trac_access#svn_access|from the Zotero code repository]]
+    * [[dev/source_code#running_svngit_builds|from the Zotero code repository]]
 ===== Find or create a translator development environment =====
-Zotero installs its translators and related code as files in the subdirectory //translators//. I.e.
+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 ''translators''. I.e.
   * if the path to your Firefox profile=<code>${FIREFOX_PROFILE}</code> then the path to your Zotero is <code>${FIREFOX_PROFILE}/zotero</code>
-  * if the path to your Zotero=<code>${FIREFOX_PROFILE}/zotero</code> then the path to your translators, and hence to your translator development environment, is <code>${FIREFOX_PROFILE}/zotero/translators</code>
+  * if the path to your Zotero=<code>${FIREFOX_PROFILE}/zotero</code> then the path to your translators, and hence to your translator development environment, is <code>${FIREFOX_PROFILE}/zotero/translators</code> (See above regarding using Zotero UI to identify the path to your current Zotero.)
 TODO: how to get alternate/uplevel versions of translators?
-TODO: Javascript-enabled tools
+=== Translator file structure ===
+At the highest level, a Zotero translator (for versions >= 2.0) consists of
+  * a single [[translators_reference_guide#translator_metadata|metadata block]], usually at the beginning of the file. The most important of its fields is the ''translatorID'', which is the global identifier for the translator.
+  * non-metadata code, consisting of
+    * a ''detectWeb'' function. This must return a string corresponding to a defined Zotero type. For a list of Zotero type names, see the values of the ''itemTypes.''* properties in [[https://www.zotero.org/trac/browser/extension/branches/2.0/chrome/locale/en-US/zotero/zotero.properties#L240|this Zotero property list]] (or a newer one).
+    * a ''doWeb'' function. This actually writes an item corresponding to your web resource to your Zotero repository.
+==== Translator development tools ====
+TODO:
+  * Zotero-enabled tools
+  * Zotero  API guides
+  * Javascript-enabled tools
+  * XPath tools
 ===== Create or modify a translator file =====
+One can generate a completely new translator file using Scaffold 2.0.
+  - Start Scaffold.
+  - In tab=Metadata, take the generated ''translatorID'', but give some values for the ''label'', ''creator'', and ''target'' fields. (Note your filename will be based on the value of the ''label'' field: e.g. if you set that to ''foo'', your file will be named ''foo.js'')
+  - In tab=Code, enter a ''detectWeb'' stub, e.g. <code>function detectWeb () {
+return "book";
+}
+</code>
+  - Click on icon=Save (second from upper left).
+  - Check your translator filespace: you should have a new file with name based on field=''label''.
+  - 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/modify-ing an existing one. This can be done in one of several ways, including
+  - working directly on an existing translator file (e.g. to fix a bug or add an feature) without modifying the ''translatorID''. Note that any Zotero update to the profile containing that file will overwrite your work.
+  - "clearing out" your copy/modified file. Open it in your editor, and
+    - in the metadata block,
+      * create a new ''translatorID'' for your copy/modified file. Edit the old field randomly, or (better) generate a new value using Scaffold 2.0.
+      * make the value of the ''label'' field match your new filename.
+    - in the code section, clear out any undesired contents from the ''detectWeb'' and ''doWeb'' functions.
+  - somewhat "between" the previous two:
+    - 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=''label'' to match your filename (minus the ''.js'' extension)
+      - assign a new value to field=''translatorID'', preferably after generating a new value using Scaffold 2.0.
+      - change the ''detectWeb'' and ''doWeb'' functions as needed.
 ===== Edit, run, test, debug =====
@@ Line 42: / Line 90: @@
 One must
-  * configure Firefox to write Zotero debugging output to a [[http://en.wikipedia.org/wiki/Terminal_emulator|terminal emulator]] (e.g. ''xterm'', ''terminal'', ''cmd'')
+  * configure Firefox to write Zotero debugging output to a [[wp>Terminal_emulator|terminal emulator]] (e.g. ''xterm'', ''terminal'', ''cmd'')
   * 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://www.zotero.org/support/debug_output#linux|linux]], [[http://www.zotero.org/support/debug_output#mac_os_x|mac]], and [[http://www.zotero.org/support/debug_output#windows_xp|windows]].
+==== 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 =====
+Once your translator works on a subset of the sites on which you believe it should work, please [[translator_overview#step_5contribute_your_translator|contribute your translator]] to the community.