Differences

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

--- dev:translator_coding [2011/04/05 03:53] – adding framework ajlyon
+++ dev:translator_coding [2011/04/20 16:52] – adding section on cross-domain ajlyon
@@ Line 88: / Line 88: @@
   }</code>
-For compatibility with Zotero Connectors, ''Zotero.selectItems'' should preferably be called with a callback function as the second parameter. This callback function receives the object with the selected items.
+For compatibility with Zotero Connectors, ''Zotero.selectItems'' should preferably be called with a callback function as the second parameter. This callback function receives the object with the selected items. FIXME We need an example of a translator that does this.
 === Batch Saving ===
@@ Line 99: / Line 99: @@
 ''Zotero.Utilities.doPost(url, postdata, callback, charset)'' sends a POST request to the specified URL (not an array), with the POST string defined in ''postdata'' and then calls function ''callback'' with two arguments: response string, and the response object. The optional ''charset'' argument forces the response to be interpreted in the specified character set.
-(Need documentation on the xmlhttp object-- link to MDC.)
+''Zotero.Utilities.processDocuments(url, callback, onDone, charset)'' sends a GET request to the specified URL or to each in an array of URLs, and then calls the function ''callback'' with XXXXX arguments: DOM document object, URL, and XXXX. FIXME the optional ''charset'' argument forces the response to be interpreted in the specified character set. This is approximately the equivalent of ''doGet'', except that it returns DOM document objects instead of strings.
-''Zotero.Utilities.processDocuments(url, callback, onDone, charset)''
+**Note:** The response objects passed to the callbacks above are [[https://developer.mozilla.org/en/XMLHttpRequest|described in detail in the MDC Documentation]].
 ''Zotero.Utilities.processAsync(sets, callbacks, onDone)'' can be used from translators to make it easier to correctly chain sets of asynchronous callbacks, since many translators that require multiple callbacks do it incorrectly [text from commit message, r4262]
 == Synchronous ==
@@ Line 120: / Line 120: @@
 <code javascript>var bibtexData = Zotero.Utilities.retrieveSource(this.bibtexLink);</code>
-===== Translator Framework =====
+== Cross-Domain Restrictions ==
-Many web translators can be written in a simplified form by using the [[dev/translator_framework|Translator Framework]], a library for translator development. Translators written in this way consist of simple sets of rules for scraping item metadata from specified portions of the page. See the [[dev/translator_framework|Translator Framework]] page for details.
+Note that all the above functions are affected by [[https://developer.mozilla.org/en/http_access_control|Firefox's HTTP Access Control]]. See the linked article at the Mozilla Developer Center for more details, but the gist of it is that ''Zotero.Utilities.retrieveDocument'' and ''Zotero.Utilities.processDocuments'' will not in general work when called from one domain, requesting documents from another domain. Such arrangements are actually fairly common for site index and search pages. The other functions, like ''Zotero.Utilities.doGet'', will work, but the response will be a simple text string which will usually have to be processed using regular expressions, not XPath or other DOM-based approaches.
+When such HTTP Access Control prevents an action, you will see an error like this in the error console or debug output:
+<code>00:41:50 Translation using Test failed:
+         message => Permission denied to access property 'documentElement'
+         fileName => chrome://zotero/content/xpcom/translation/browser_firefox.js
+         lineNumber => 451</code>
+====== Import Translators ======
+====== Export Translators ======
+====== Search Translators ======
+====== Utility functions ======
+Zotero provides several utility functions for translators to use. Some of them are used for asynchronous and synchronous HTTP requests; those are [[#batch_saving|discussed above]]. In addition to those HTTP functions and the many standard functions provided by JavaScript, Zotero provides:
+  * ''Zotero.Utilities.capitalizeTitle(title, ignorePreference)''
+  * ''Zotero.Utilities.cleanAuthor(author, creatorType, hasComma)''
+  * ''Zotero.Utilities.trimInternal(text)''
-====== The Translator Object ======
+====== Working with the Translator object ======
+=== Methods ===
   * ''Zotero.loadTranslator(type)''
   * ''translator.setSearch(OpenURL ContextObject)''
+For search translators. Takes a skeleton item object and ... FIXME
   * ''translator.setString(string)''
+For import translators. Sets the string that the translator will import from.
   * ''translator.getTranslators()''
+Returns an array of translators that should be able to run on the given data. That is, those translators that return a non-false value for ''detectImport'', ''detectSearch'' or ''detectWeb'' when passed the input given with ''setString'', ''setSearch'', etc.
   * ''translator.setTranslator(translator)'' Takes translator object (returned by ''getTranslators(..)'', or the UUID of a translator.
   * ''translator.setHandler(event, callback)''
@@ Line 151: / Line 169: @@
 search.translate();
 </code>
+===== Translator Framework =====
+Many web translators can be written in a simplified form by using the [[dev/translator_framework|Translator Framework]], a library for translator development. Translators written in this way consist of simple sets of rules for scraping item metadata from specified portions of the page. See the [[dev/translator_framework|Translator Framework]] page for details.