Differences

This shows you the differences between two versions of the page.

--- dev:client_coding:javascript_api [2019/01/22 04:26] – [API Methods] dstillman
+++ dev:client_coding:javascript_api [2019/06/11 03:44] – [Running Ad Hoc JavaScript in Zotero] dstillman
@@ Line 1: / Line 1: @@
-<html><p id="zotero-5-update-warning" style="color: red; font-weight: bold">The examples on this page have not been updated for Zotero 5 and should not currently be used.</p></html>
 ====== Zotero JavaScript API ======
@@ Line 11: / Line 8: @@
 ===== Running Ad Hoc JavaScript in Zotero =====
-Zotero 5.0.61 and later include an option to run arbitrary privileged JavaScript:
+Zotero includes an option to run arbitrary privileged JavaScript:
   - In the Advanced pane of the Zotero preferences, select Config Editor, and then set ''devtools.chrome.enabled'' to ''true'' and restart Zotero.
@@ Line 20: / Line 17: @@
 In synchronous mode, the value of the final line will appear in the right-hand pane.
+===== Zotero Code Architecture =====
-(Before Zotero 5.0.61 is released, you'll need to install the [[:dev_builds|Zotero beta]] to use this feature.)
+==== Window Scope vs. Non-Window Scope ===
-===== Window Scope vs. Non-Window Scope ====
 Zotero code exists in either window scope and non-window scope.
@@ Line 44: / Line 41: @@
 </code>
 (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 extensions can use the system to perform additional operations when specific events occur---say, to sync item metadata with a web-based tool.
+==== 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 API.
 Available events:
@@ Line 340: / Line 338: @@
 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://addons.mozilla.org/en-US/firefox/addon/execute-js/|Execute JS]] Firefox extension to interact with Zotero via JavaScript. (Advanced users can also use the Firefox Browser Console or Scratchpad in Browser mode after enable chrome/add-on debugging in the Web Console settings.) Back up your database first, and temporarily disable auto-sync in the Sync pane of the Zotero preferences.
+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 "JS-Code to execute" box, make any necessary changes, and click "Execute".
 ==== Example: Item Field Changes ====
@@ Line 353: / Line 349: @@
 var fieldID = Zotero.ItemFields.getID(fieldName);
-var s = new Zotero.Search;
+var s = new Zotero.Search();
+s.libraryID = Zotero.Libraries.userLibraryID;
 s.addCondition(fieldName, 'is', oldValue);
-var ids = s.search();
+var ids = await s.search();
-if (ids) {
+if (!ids.length) {
-	for(var i in ids) {
+    return "No items found";
-		var item = Zotero.Items.get(ids[i]);
-		var mappedFieldID = Zotero.ItemFields.getFieldIDFromTypeAndBase(item.itemTypeID, fieldName);
-		item.setField(mappedFieldID ? mappedFieldID : fieldID, newValue);
-		item.save();
-	}
-	alert(ids.length + " items updated");
 }
-else {
+await Zotero.DB.executeTransaction(async function () {
-	alert("No items found");
+    for (let id of ids) {
-}</code>
+        let item = await Zotero.Items.getAsync(id);
+        let mappedFieldID = Zotero.ItemFields.getFieldIDFromTypeAndBase(item.itemTypeID, fieldName);
+        item.setField(mappedFieldID ? mappedFieldID : fieldID, newValue);
+        await item.save();
+    }
+});
+return ids.length + " item(s) updated";</code>
+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://api.zotero.org/itemFields?pprint=1.
+https://api.zotero.org/itemFields?pprint=1.
 ==== Example: Delete Tags By Name ====
+<html><p id="zotero-5-update-warning" style="color: red; font-weight: bold">This example has not been updated for Zotero 5 and should not currently be used.</p></html>
 <code javascript>var tags = ["foo", "bar", "baz"];
@@ Line 386: / Line 387: @@
 ==== Example: Delete Tags By Part of Name ====
+<html><p id="zotero-5-update-warning" style="color: red; font-weight: bold">This example has not been updated for Zotero 5 and should not currently be used.</p></html>
 <code javascript>var tags = ["foo", "bar", "baz"];