Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
dev:client_coding:javascript_api [2019/01/22 04:26] – [API Methods] dstillman | dev:client_coding:javascript_api [2020/04/16 16:03] – [Running Ad Hoc JavaScript in Zotero] dstillman | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | < | ||
- | |||
- | |||
====== Zotero JavaScript API ====== | ====== Zotero JavaScript API ====== | ||
Line 11: | Line 8: | ||
===== Running Ad Hoc JavaScript in Zotero ===== | ===== Running Ad Hoc JavaScript in Zotero ===== | ||
- | Zotero | + | Zotero |
- | | + | - In the Tools → Developer |
- | | + | - In the window that opens, enter some JavaScript in the Code textbox and click Run or press Cmd-R/ |
- | - In the window that opens, enter JavaScript in the Code textbox and click Run or press Cmd-R/ | + | |
- | To run asynchronous code, check the "Run as async function" | + | When running **asynchronous** code containing '' |
- | In synchronous mode, the value of the final line will appear in the right-hand pane. | + | <code javascript> |
+ | var items = Zotero.getActiveZoteroPane().getSelectedItems(); | ||
+ | return items; | ||
+ | </ | ||
+ | |||
+ | In **synchronous** mode, the value of the final line will appear in the right-hand pane. The same result as above could be achieved in synchronous mode with | ||
+ | |||
+ | <code javascript> | ||
+ | var items = Zotero.getActiveZoteroPane().getSelectedItems(); | ||
+ | items; | ||
+ | </ | ||
+ | ===== Zotero Code Architecture ===== | ||
- | (Before Zotero 5.0.61 is released, you'll need to install the [[: | + | ==== Window Scope vs. Non-Window Scope === |
- | ===== Window Scope vs. Non-Window Scope ==== | + | |
Zotero code exists in either window scope and non-window scope. | Zotero code exists in either window scope and non-window scope. | ||
Line 44: | Line 50: | ||
</ | </ | ||
(The Zotero pane will always be available unless the main window is closed, as is possible on macOS.) | (The Zotero pane will always be available unless the main window is closed, as is possible on macOS.) | ||
- | ===== Notification System ===== | ||
- | Zotero has a built-in notification system that allows other privileged code to be notified when a change is made via the data layer---for example, when an item is added to the library. Within Zotero itself, this is used mostly to update the UI when items change, but external | + | ==== Notification System ==== |
+ | |||
+ | Zotero has a built-in notification system that allows other privileged code to be notified when a change is made via the data layer — for example, when an item is added to the library. Within Zotero itself, this is used mostly to update the UI when items change, but extensions can use the system to perform additional operations when specific events occur — say, to sync item metadata with a web-based | ||
Available events: | Available events: | ||
Line 235: | Line 242: | ||
<code javascript> | <code javascript> | ||
- | ===== Managing citations and bibliographies | + | ==== Managing citations and bibliographies ==== |
TODO: this is pretty sparse. | TODO: this is pretty sparse. | ||
- | ==== Getting a bibliography for an array of items: | + | === Getting a bibliography for an array of items: === |
Here we use Zotero' | Here we use Zotero' | ||
- | specified in Zotero' | + | specified in Zotero' |
+ | bibliography from all currently selected items. | ||
- | First we start with a list of as in the previous entry. | + | <code javascript> |
- | + | var qc = Zotero.QuickCopy; | |
- | <code javascript> | + | var format |
- | var biblio | + | if (format.split(" |
- | var biblio_html_format = cite.html; | + | |
- | var biblio_txt | + | } |
+ | var biblio = qc.getContentFromItems(items, | ||
+ | var biblio_html_format = biblio.html; | ||
+ | var biblio_txt = biblio.text; | ||
</ | </ | ||
- | ==== Get a list of available styles | + | If you instead want to have the citation string then simply replace the 7th |
+ | line with '' | ||
+ | |||
+ | |||
+ | === Get a list of available styles === | ||
<code javascript> | <code javascript> | ||
Line 264: | Line 279: | ||
</ | </ | ||
- | TODO: get citations. | + | TODO: change the style. |
especially RTF | especially RTF | ||
Line 338: | Line 353: | ||
===== Batch Editing ===== | ===== Batch Editing ===== | ||
- | The JavaScript API can provide | + | The JavaScript API provides |
- | First, install the [[https:// | + | Before proceeding, back up your [[:zotero_data|Zotero data directory]] and temporarily disable auto-sync in the Sync pane of the Zotero preferences. |
- | + | ||
- | In Execute JS, switch the target window to an open browser window, paste the relevant code into the " | + | |
==== Example: Item Field Changes ==== | ==== Example: Item Field Changes ==== | ||
Line 353: | Line 366: | ||
var fieldID = Zotero.ItemFields.getID(fieldName); | var fieldID = Zotero.ItemFields.getID(fieldName); | ||
- | var s = new Zotero.Search; | + | var s = new Zotero.Search(); |
+ | s.libraryID = Zotero.Libraries.userLibraryID; | ||
s.addCondition(fieldName, | s.addCondition(fieldName, | ||
- | var ids = s.search(); | + | var ids = await s.search(); |
- | if (ids) { | + | if (!ids.length) { |
- | for(var i in ids) { | + | |
- | var item = Zotero.Items.get(ids[i]); | + | |
- | var mappedFieldID = Zotero.ItemFields.getFieldIDFromTypeAndBase(item.itemTypeID, | + | |
- | item.setField(mappedFieldID ? mappedFieldID : fieldID, newValue); | + | |
- | item.save(); | + | |
- | } | + | |
- | alert(ids.length + " items updated"); | + | |
} | } | ||
- | else { | + | await Zotero.DB.executeTransaction(async function () { |
- | alert("No items found"); | + | |
- | }</ | + | let item = await Zotero.Items.getAsync(id); |
+ | let mappedFieldID = Zotero.ItemFields.getFieldIDFromTypeAndBase(item.itemTypeID, | ||
+ | item.setField(mappedFieldID ? mappedFieldID : fieldID, newValue); | ||
+ | await item.save(); | ||
+ | | ||
+ | }); | ||
+ | return ids.length + " item(s) updated"; | ||
- | The list of field names to use can be retrieved via the server | + | The list of field names to use can be retrieved via the web API: |
+ | |||
+ | https:// | ||
+ | |||
+ | ==== Example: Creator Name Changes ==== | ||
+ | |||
+ | Edit the first four lines as necessary: | ||
+ | |||
+ | <code javascript> | ||
+ | var newFirstName = " | ||
+ | var newLastName = " | ||
+ | var newFieldMode = 0; // 0: two-field, 1: one-field (with empty first name) | ||
+ | |||
+ | var s = new Zotero.Search(); | ||
+ | s.libraryID = Zotero.Libraries.userLibraryID; | ||
+ | s.addCondition(' | ||
+ | var ids = await s.search(); | ||
+ | if (!ids.length) { | ||
+ | return "No items found"; | ||
+ | } | ||
+ | await Zotero.DB.executeTransaction(async function () { | ||
+ | for (let id of ids) { | ||
+ | let item = await Zotero.Items.getAsync(id); | ||
+ | let creators = item.getCreators(); | ||
+ | let newCreators = []; | ||
+ | for (let creator of creators) { | ||
+ | if (`${creator.firstName} ${creator.lastName}`.trim() == oldName) { | ||
+ | creator.firstName = newFirstName; | ||
+ | creator.lastName = newLastName; | ||
+ | creator.fieldMode = newFieldMode; | ||
+ | } | ||
+ | newCreators.push(creator); | ||
+ | } | ||
+ | item.setCreators(newCreators); | ||
+ | await item.save(); | ||
+ | } | ||
+ | }); | ||
+ | return ids.length + " item(s) updated";</ | ||
==== Example: Delete Tags By Name ==== | ==== Example: Delete Tags By Name ==== | ||
+ | |||
+ | < | ||
<code javascript> | <code javascript> | ||
Line 386: | Line 439: | ||
==== Example: Delete Tags By Part of Name ==== | ==== Example: Delete Tags By Part of Name ==== | ||
+ | |||
+ | < | ||
<code javascript> | <code javascript> |