| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| dev:translators:coding [2023/07/20 03:53] – Add documentation for text() and attr(): describe their behaviour and usefulness. zoe | dev:translators:coding [2023/08/04 01:14] (current) – [Search Translators] dstillman |
|---|
| ===== doWeb ===== | ===== 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. | ''doWeb'' is run when a user, wishing to save one or more items, activates the selected translator. It can be seen as the entry point of the translation process. |
| |
| The signature of ''doWeb'' should be | The signature of ''doWeb'' should be |
| |
| Here ''doc'' refers to the DOM object of the web page that the user wants to save as a Zotero item, and ''url'' is the page's URL as a string. | Here ''doc'' refers to the DOM object of the web page that the user wants to save as a Zotero item, and ''url'' is the page's URL as a string. |
| | |
| | In this section, we will describe the common tasks in the translation workflow started by ''doWeb()''. |
| |
| ==== Saving Single Items ==== | ==== Saving Single Items ==== |
| |
| Another less-used helper function ''innerText()'' has the same signature as ''text()'', but it differs from the latter by returning the selected node's ''[[https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText|innerText]]'' value, which is affected by how the node's content would have been rendered. | Another less-used helper function ''innerText()'' has the same signature as ''text()'', but it differs from the latter by returning the selected node's ''[[https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText|innerText]]'' value, which is affected by how the node's content would have been rendered. |
| | |
| | In addition, you can always use the API functions ''querySelector'' and ''querySelectorAll'' directly, but the helper functions should be preferred when they are adequate for the job. |
| | |
| | In some older translator code, you are likely to encounter node-selection expressed by XPath. Although XPath has its uses, for the most common types of scraping the selector-based functions should be preferred because of the simpler syntax of selectors. |
| |
| === Metadata === | === Metadata === |
| </code> | </code> |
| |
| ''doSearch'' should augment the provided item with additional information and call ''item.complete()'' when done. Since search translators are never called directly, but only by other translators or by the [[:getting_stuff_into_your_library#add_item_by_identifier|Add Item by Identifier]] (magic wand) function, it is common for the information to be further processed an [[#calling_other_translators|''itemDone'' handler]] specified in the calling translator. | ''doSearch'' should augment the provided item with additional information and call ''item.complete()'' when done. Since search translators are never called directly, but only by other translators or by the [[:adding_items_to_zotero#add_item_by_identifier|Add Item by Identifier]] (magic wand) function, it is common for the information to be further processed an [[#calling_other_translators|''itemDone'' handler]] specified in the calling translator. |
| ====== Further Reference ====== | ====== Further Reference ====== |
| ===== Utility Functions ===== | ===== Utility Functions ===== |
Upgrade Storage