Differences

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

--- dev:client_coding:javascript_api [2019/01/22 04:27] – dstillman
+++ dev:client_coding:javascript_api [2019/08/18 05:41] – [Running Ad Hoc JavaScript in Zotero] Add examples zuphilip
@@ 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.
+  - In the Tools → Developer menu, select Run JavaScript. Opening the Error Console, which appears in the same menu, will also be helpful.
-  - In the Tools menu, select Run JavaScript. Open the Error Console, which also appears in Tools, will also be helpful.
   - In the window that opens, enter JavaScript in the Code textbox and click Run or press Cmd-R/Ctrl-R.
-To run asynchronous code, check the "Run as async function" checkbox. This runs the entered code wrapped in an [[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function|async function]], allowing you to use ''await'' to wait for the resolution of promises returned by functions. Most Zotero functions that access the database, disk, or network are asynchronous. In this mode, the value of a ''return'' statement will be displayed in the right-hand pane upon successful completion.
+When running **asynchronous** code containing ''await'', the entered code is wrapped in an [[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function|async function]], allowing you to wait for the resolution of promises returned by functions. Most Zotero functions that access the database, disk, or network are asynchronous. In this mode, the value of a ''return'' statement will be displayed in the right-hand pane upon successful completion. E.g. returning the currently selected item(s)
-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;
+</code>
-(Before Zotero 5.0.61 is released, you'll need to install the [[:dev_builds|Zotero beta]] to use this feature.)
+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 synchonous mode with
+<code javascript>
+var items = Zotero.getActiveZoteroPane().getSelectedItems();
+items;
+</code>
 ===== Zotero Code Architecture =====
@@ Line 344: / Line 347: @@
 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 357: / Line 358: @@
 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 390: / Line 396: @@
 ==== 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"];