| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| dev:translator_coding [2011/02/02 12:32] – rmzelle | dev:translator_coding [2017/11/12 19:53] (current) – external edit 127.0.0.1 |
|---|
| Below we will describe how the ''detect*'' and ''do*'' functions of Zotero [[translators]] can and should be coded. If you are unfamiliar with JavaScript, make sure to check out a [[https://developer.mozilla.org/en/JavaScript/A_re-introduction_to_JavaScript|JavaScript tutorial]] to get familiar with the syntax. In addition to the information on this page, it can often be very informative to look at existing translators to see how things are done. | <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> |
| |
| ====== Web Translators ====== | |
| |
| ===== detectWeb ===== | See [[dev/translators/Coding]]. |
| | |
| ''detectWeb'' is run to determine whether item metadata can indeed be retrieved from the webpage. The return value of this function should be the detected item type (e.g. "journalArticle", see the [[http://gsl-nagoya-u.net/http/pub/csl-fields/index.html|overview of Zotero item types]]), or, if multiple items are found, "multiple". | |
| | |
| ''detectWeb'' receives two arguments, the webpage document object and URL (typically named ''doc'' and ''url''). In some cases, the URL provides all the information needed to determine whether item metadata is available, allowing for a simple ''detectWeb'' function, e.g. (example from ''Cell Press.js''): | |
| | |
| <code javascript>function detectWeb(doc, url) { | |
| | |
| if (url.indexOf("search/results") != -1) { | |
| return "multiple"; | |
| } else if (url.indexOf("content/article") != -1) { | |
| return "journalArticle"; | |
| } | |
| }</code> | |
| | |
| ===== doWeb ===== | |
| | |
| ''doWeb'' is run when a user, wishing to save one or more items, activates the selected translator. Sidestepping the retrieval of item metadata, we'll first focus on how ''doWeb'' can be used to save retrieved item metadata (as well as attachments and notes) to your Zotero library. | |
| | |
| ==== Saving Items ==== | |
| | |
| === Metadata === | |
| | |
| The first step towards saving an item is to create an item object of the desired [[http://gsl-nagoya-u.net/http/pub/csl-fields/index.html|item type]] (examples from "NCBI PubMed.js"): | |
| | |
| <code javascript>var newItem = new Zotero.Item("journalArticle");</code> | |
| | |
| Metadata can then be stored in the properties of the object. Of the different fields available for the chosen item type (see the [[http://gsl-nagoya-u.net/http/pub/csl-fields/index.html|Field Index]]), only the title is required. E.g.: | |
| | |
| <code javascript>var title = article.ArticleTitle.text().toString(); | |
| newItem.title = title; | |
| | |
| var PMID = citation.PMID.text().toString(); | |
| newItem.url = "http://www.ncbi.nlm.nih.gov/pubmed/" + PMID;</code> | |
| | |
| After all metadata has been stored in the item object, the item can be saved: | |
| | |
| <code javascript>newItem.complete();</code> | |
| | |
| This process can be repeated (e.g. using a loop) to save multiple items. | |
| | |
| === Attachments === | |
| | |
| Attachments may be saved alongside item metadata via the item object's ''attachments'' property. Common attachment types are full-text PDFs, links and snapshots. An example from "Pubmed Central.js": | |
| | |
| <code javascript>var linkurl = "http://www.ncbi.nlm.nih.gov/pmc/articles/PMC" + ids[i] + "/"; | |
| newItem.attachments = [{ | |
| url: linkurl, | |
| title: "PubMed Central Link", | |
| mimeType: "text/html", | |
| snapshot: false}]; | |
| | |
| var pdfurl = "http://www.ncbi.nlm.nih.gov/pmc/articles/PMC" + ids[i] + "/pdf/" + pdfFileName; | |
| newItem.attachments.push({ | |
| title:"PubMed Central Full Text PDF", | |
| mimeType:"application/pdf", | |
| url:pdfurl});</code> | |
| | |
| An attachment can only be saved if the source is indicated. The source is often a URL (set on the ''url'' property), but can also be a file path (set on ''path'') or a document object (set on ''document''). Other properties that can be set are ''mimeType'' ("text/html" for webpages, "application/pdf" for PDFs), ''title'', and ''snapshot'' (if the latter is set to ''false'', an attached webpage is always saved as a link). | |
| | |
| :?: Rintze: is it preferable to use ''document'' instead of ''url'', if possible? (would this eliminate the reloading of a loaded webpage?) | |
| | |
| === Notes === | |
| | |
| Notes are saved similarly to attachments. The content of the note, which should consist of a string, should be stored in the ''note'' property of the item's ''notes'' property. A title, stored in the ''title'' property, is optional. E.g.: | |
| | |
| <code javascript>bbCite = "Bluebook citation: " + bbCite + "."; | |
| newItem.notes.push({note:bbCite});</code> | |
Upgrade Storage