Differences

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

--- dev:translator_development_outside_scaffold [2010/07/24 16:56] – added tomrochewiki
+++ dev:translator_development_outside_scaffold [2017/11/12 19:53] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
+<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>
 ===== Overview =====
@@ Line 21: / Line 27: @@
   - 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]]
-    * [[dev/svn_and_trac_access#development_xpi|a development XPI]]
+    * [[/support/dev_builds|a development XPI]]
-    * [[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 =====
@@ Line 35: / Line 41: @@
 === Translator file location ===
-Zotero installs its translators and related code as files in the subdirectory //translators//. I.e.
+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> (See above regarding using Zotero UI to identify the path to your current Zotero.)
@@ Line 44: / Line 50: @@
 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.
+  * 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 ''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.
+    * a ''doWeb'' function. This actually writes an item corresponding to your web resource to your Zotero repository.
 ==== Translator development tools ====
@@ Line 58: / Line 64: @@
 ===== 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 =====