| Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision |
| dev:how_to_write_a_zotero_translator_plusplus [2010/07/28 09:46] – close double-single-quotes! tomrochewiki | dev:how_to_write_a_zotero_translator_plusplus [2017/11/12 19:53] – external edit 127.0.0.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> |
| | |
| | |
| | **Note: This guide's advice on translator code [[https://github.com/zotero/translators/pull/1282#issuecomment-287574730|may be outdated]].** Instead, model your code on [[https://github.com/zotero/translators/pulls|recently updated translators]], [[https://github.com/zuphilip/translators/wiki/Common-code-blocks-for-translators|common code templates]], [[https://www.zotero.org/support/dev/translators/coding|the translator coding documentation]], and search for answers in the [[https://forums.zotero.org/discussions|Zotero Forums]] and [[https://github.com/zotero/translators/issues|on GitHub]]. |
| | |
| ===== Chapter 0: Introduction ===== | ===== Chapter 0: Introduction ===== |
| |
| Be sure you have the most up to date version of Zotero. You can find this information on the [[http://www.zotero.org/|Zotero website]]. | Be sure you have the most up to date version of Zotero. You can find this information on the [[http://www.zotero.org/|Zotero website]]. |
| |
| ==== Scaffold 2.0 ==== | ==== Scaffold ==== |
| |
| install Scaffold from [[http://bitbucket.org/rmzelle/scaffold/downloads|here]] (temporarily) | Install [[https://www.zotero.org/support/dev/translators/scaffold Scaffold]]. Note that it has been updated more recently than most of this wiki, and some features may have changed. |
| |
| The makers of Zotero created Scaffold specifically for writing translators. It's a sort of a "sandbox," which means you can muck around with the code without worrying about really messing anything up, and it automates some tasks. In this guide, all code will be written, tested, and retested in Scaffold. | The makers of Zotero created Scaffold specifically for writing translators. It's a sort of a "sandbox," which means you can muck around with the code without worrying about really messing anything up, and it automates some tasks. In this guide, all code will be written, tested, and retested in Scaffold. |
| * Words that appear between ''<!--'' and ''-->'' are HTML comments, intended for human readers, ignored by the browser. HTML comments do not tell your browser to do anything, but can be used to provide valuable information to anyone reading your code. | * Words that appear between ''<!--'' and ''-->'' are HTML comments, intended for human readers, ignored by the browser. HTML comments do not tell your browser to do anything, but can be used to provide valuable information to anyone reading your code. |
| * If you do not recognize these markup structures, or find it difficult to follow this chapter, please take the [[http://www.w3schools.com/html/default.asp|W3Schools HTML tutorial]] before continuing. | * If you do not recognize these markup structures, or find it difficult to follow this chapter, please take the [[http://www.w3schools.com/html/default.asp|W3Schools HTML tutorial]] before continuing. |
| | |
| | ==== The Document Object Model ==== |
| |
| <html> | <html> |
| |
| <div class="box1"> | |
| <p class="style2">Note: Words appearing between < > are HTML elements.</p> | |
| <p class="style2">Words that appear between <!–– and ––> are HTML comments, intended for human readers, ignored by the browser.</p> | |
| <p class="style2">HTML comments do not tell your browser to do anything, but can be used to provide valuable information to anyone reading your code. If you do not recognize these markup structures, or find it difficult to follow this chapter, please take the <a href="http://www.w3schools.com/html/default.asp">W3Schools HTML tutorial</a> before continuing.</p> | |
| </div> | |
| | |
| <h2 id="s4p1">What is the DOM?</h2> | |
| |
| <p class="style1">DOM stands for "Document Object Model."</p> | <p class="style1">DOM stands for "Document Object Model."</p> |
| <p class="style1">Web pages are actually comprised of a series of nodes. These nodes are organized in a particular hierarchy, as defined by the person who wrote the web page, according to how they decided they wanted the page to function. But before we discuss that further, let's take a look at what a web page really is.</p> | <p class="style1">Web pages are actually comprised of a series of nodes. These nodes are organized in a particular hierarchy, as defined by the person who wrote the web page, according to how they decided they wanted the page to function. But before we discuss that further, let's take a look at what a web page really is.</p> |
| |
| <h2 id="s4p2">Understanding HTML structure</h2> | </html> |
| | |
| | ==== Understanding HTML structure ==== |
| | |
| | <html> |
| |
| <p class="style1">If you've ever written a basic web page, you know that it is really just an HTML document. These documents contain the page's content — the words, links, images — as well as a series of tags that help your browser understand at what it is looking.</p> | <p class="style1">If you've ever written a basic web page, you know that it is really just an HTML document. These documents contain the page's content — the words, links, images — as well as a series of tags that help your browser understand at what it is looking.</p> |
| <p class="style1">This network of relationships between nodes in an HTML document is the DOM.</p> | <p class="style1">This network of relationships between nodes in an HTML document is the DOM.</p> |
| |
| <h2 id="s4p3">Why is the DOM important to you?</h2> | </html> |
| | |
| | ==== Why is the DOM important to you? ==== |
| | |
| | <html> |
| |
| <p class="style1">The DOM is how you give your computer directions to find a particular piece of information in an HTML document. Computers can't jump to a desired element node the way our eyes can jump to a particular point on the screen. They need to crawl to that node, visiting all the connected parent nodes along the way, starting at the root.</p> | <p class="style1">The DOM is how you give your computer directions to find a particular piece of information in an HTML document. Computers can't jump to a desired element node the way our eyes can jump to a particular point on the screen. They need to crawl to that node, visiting all the connected parent nodes along the way, starting at the root.</p> |
| <p class="style1">Note: Notice that "Cool" is not the 4th <td> node. Rather, it is the 2nd <td> of the 2nd <tr>. This distinction will become important later (and will be addressed in <a href="/member-projects/zotero-guide/chapter5.html">Chapter 5</a>).</p> | <p class="style1">Note: Notice that "Cool" is not the 4th <td> node. Rather, it is the 2nd <td> of the 2nd <tr>. This distinction will become important later (and will be addressed in <a href="/member-projects/zotero-guide/chapter5.html">Chapter 5</a>).</p> |
| |
| <h3>A quick note on aunts and uncles</h3> | </html> |
| | |
| | === A quick note on aunts and uncles === |
| | |
| | <html> |
| |
| <p class="style1">We have already learned a little family jargon to help us understand the DOM. We know that <tbody> is the grandparent of <td>. We know that <head> and <body> are siblings. But, not all nodes are related. In the DOM, aunts and uncles count for nothing.</p> | <p class="style1">We have already learned a little family jargon to help us understand the DOM. We know that <tbody> is the grandparent of <td>. We know that <head> and <body> are siblings. But, not all nodes are related. In the DOM, aunts and uncles count for nothing.</p> |
| </table> | </table> |
| |
| <h2 id="s4p4">Practice</h2> | </html> |
| | |
| | ==== Practice ==== |
| | |
| | <html> |
| |
| <p class="style1">If you feel confident that you understand the DOM and how to find various element nodes in it, you can skip ahead to the next section. If you would like some more practice, here is a sample HTML document and some questions through which to work.</p> | <p class="style1">If you feel confident that you understand the DOM and how to find various element nodes in it, you can skip ahead to the next section. If you would like some more practice, here is a sample HTML document and some questions through which to work.</p> |
| <p class="style1"><a href="/member-projects/zotero-guide/chapter4answers.html">View Answers</a></p> | <p class="style1"><a href="/member-projects/zotero-guide/chapter4answers.html">View Answers</a></p> |
| |
| <h2 id="s4p5">What you should understand before moving on</h2> | </html> |
| | |
| | ==== What you should understand before moving on ==== |
| | |
| | <html> |
| |
| <ul class="indent"> | <ul class="indent"> |
| </ul> | </ul> |
| |
| <h2 id="s4p6">Further Reading</h2> | </html> |
| | |
| | ==== Further Reading ==== |
| | |
| | <html> |
| |
| <ul class="indent"> | <ul class="indent"> |
| |
| </html> | </html> |
| |
| |
| ===== Chapter 5: XPath directions ===== | ===== Chapter 5: XPath directions ===== |
| |
| [[http:/XPath directions/niche-canada.org/member-projects/zotero-guide/chapter5.html|HWZT chapter 5 (XPath directions)]]: | [[http://niche-canada.org/member-projects/zotero-guide/chapter5.html|HWZT chapter 5 (XPath directions)]]: |
| |
| The {DOM Inspector + XPather} workflow differs from that of Solvent. After opening the [[http://niche-canada.org/member-projects/zotero-guide/sample1.html|first sample page]], | The {DOM Inspector + XPather} workflow differs from that of Solvent. After opening the [[http://niche-canada.org/member-projects/zotero-guide/sample1.html|first sample page]], |
| - Open DOM Inspector (aka //DI//) with C-S-i or from the Firefox main menu with Tools>DOM Inspector. XPather functionality is available from UI within the DI window. | - Open DOM Inspector (aka //DI//) with CTRL+SHIFT+C or from the Firefox main menu with Tools>DOM Inspector. XPather functionality is available from UI within the DI window. |
| - Hit button=Inspect at the upper right of the DI window. This will open pane=Browser in the DI window displaying the contents of the first sample page. | - Hit button=Inspect at the upper right of the DI window. This will open pane=Browser in the DI window displaying the contents of the first sample page. |
| - To test the XPath string denoting the heading (text="Method and Meaning in Canadian Environmental History") of the first sample page, | - To test the XPath string denoting the heading (text="Method and Meaning in Canadian Environmental History") of the first sample page, |
| - The URI of the sample page has changed since HWZT, so you will need to enter Target=<code>http://niche-canada.org/member-projects/zotero-guide/</code> | - The URI of the sample page has changed since HWZT, so you will need to enter Target=<code>http://niche-canada.org/member-projects/zotero-guide/</code> |
| - Hit button="Test Regex". You should get a result, in the "Test Frame" on the right of the tab, similar to that described in HWZT. | - Hit button="Test Regex". You should get a result, in the "Test Frame" on the right of the tab, similar to that described in HWZT. |
| - Instead of <code>Click on the "Detect Code" tab</code>, click on tab=Code. | - Instead of <code>Click on the "Detect Code" tab</code>, click on tab=Code. This is the tab where code should be entered. |
| - In that tab enter <code>function detectWeb(doc, url) { | - To excute code and debug, HWZT has you click an "Execute" button with a thunderbolt icon. In newer versions of Scaffold, the single execute button as been replaced by one "Run doWeb" button (thunderbolt icon) and one "Run detectWeb" button (eye icon). Starting in HWZT exampe 11.6, you'll be writing detectWeb functions, so you'll need to click the "Run detectWeb" button to run your detectWeb function. For example, at example 11.6, when you click "Run detectWeb", you should get results like <code>12:00:00 Title:</code> |
| | |
| | |
| | As noted at HWZT, example 11.4, certain code needs to be included inside the top of every Function in which you have an XPath (container). So, putting everything together, the code for example 11.6 should look like this: <code>function detectWeb(doc, url) { |
| var namespace = doc.documentElement.namespaceURI; | var namespace = doc.documentElement.namespaceURI; |
| var nsResolver = namespace ? function(prefix) { | var nsResolver = namespace ? function(prefix) { |
| Zotero.debug(myXPathObject); | Zotero.debug(myXPathObject); |
| }</code> | }</code> |
| - Click on icon="Run detectWeb" (the eye): you should get results like <code>12:00:00 Title:</code> | |
| |
| The code for the second complete Scaffold example (from "Example 11.10") is similarly | The code for the second complete Scaffold example (from "Example 11.9") is similarly |
| <code>function detectWeb(doc, url) { | <code>function detectWeb(doc, url) { |
| var namespace = doc.documentElement.namespaceURI; | var namespace = doc.documentElement.namespaceURI; |
Upgrade Storage