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 [2019/01/22 04:37] – dstillman | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | < | ||
- | |||
- | |||
====== Zotero JavaScript API ====== | ====== Zotero JavaScript API ====== | ||
Line 22: | Line 19: | ||
(Before Zotero 5.0.61 is released, you'll need to install the [[: | (Before Zotero 5.0.61 is released, you'll need to install the [[: | ||
- | ===== Window Scope vs. Non-Window Scope ==== | + | |
+ | ===== Zotero Code Architecture ===== | ||
+ | |||
+ | ==== 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 44: | ||
</ | </ | ||
(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 340: | Line 341: | ||
The JavaScript API can provide a powerful way to script changes to your Zotero library. The common case of search-and-replace is accomplished easily using a basic script. | The JavaScript API can provide a powerful way to script changes to your Zotero library. The common case of search-and-replace is accomplished easily using a basic script. | ||
- | 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 352: | ||
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 web API: | ||
- | The list of field names to use can be retrieved via the server API: https:// | + | https:// |
==== Example: Delete Tags By Name ==== | ==== Example: Delete Tags By Name ==== | ||
+ | |||
+ | < | ||
<code javascript> | <code javascript> | ||
Line 386: | Line 390: | ||
==== Example: Delete Tags By Part of Name ==== | ==== Example: Delete Tags By Part of Name ==== | ||
+ | |||
+ | < | ||
<code javascript> | <code javascript> |