Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
dev:client_coding:javascript_api [2019/06/11 03:44]
dstillman [Running Ad Hoc JavaScript in Zotero]
dev:client_coding:javascript_api [2020/04/16 16:03] (current)
dstillman [Running Ad Hoc JavaScript in Zotero]
Line 10: Line 10:
 Zotero includes 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 some JavaScript in the Code textbox and click Run or press Cmd-R/​Ctrl-R.
-  - 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>​ 
 + 
 +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; 
 +</​code>​
 ===== Zotero Code Architecture ===== ===== Zotero Code Architecture =====
  
Line 233: Line 242:
 <code javascript>​var items = await Zotero.Items.getAsync(results);</​code>​ <code javascript>​var items = await Zotero.Items.getAsync(results);</​code>​
  
-===== Managing citations and bibliographies ​=====+==== Managing citations and bibliographies ====
  
 TODO:  this is pretty sparse. ​ the rtfscan code is a good place to look for some guidance. TODO:  this is pretty sparse. ​ the rtfscan code is a good place to look for some guidance.
  
-==== Getting a bibliography for an array of items: ​====+=== Getting a bibliography for an array of items: ===
  
 Here we use Zotero'​s Quick Copy functions to get a bibliography in the style Here we use Zotero'​s Quick Copy functions to get a bibliography in the style
-specified in Zotero'​s preferences.+specified in Zotero'​s preferences. We will in the following example create this 
 +bibliography from all currently selected items.
  
-First we start with a list of as in the previous entry. +<code javascript>​var items = Zotero.getActiveZoteroPane().getSelectedItems();​ 
- +var qc = Zotero.QuickCopy;​ 
-<code javascript>​var qc = Zotero.QuickCopy;​ +var format ​= Zotero.Prefs.get("​export.quickCopy.setting"​)
-var biblio ​qc.getContentFromItems([item], ​Zotero.Prefs.get("​export.quickCopy.setting"​));​ +if (format.split("​="​)[0] !== "​bibliography"​) { 
-var biblio_html_format = cite.html; +   ​alert("​No bibliography style is choosen in the settings for QuickCopy."​);​ 
-var biblio_txt ​ cite.text; ​+
 +var biblio = qc.getContentFromItems(items,​ format); 
 +var biblio_html_format = biblio.html; 
 +var biblio_txt = biblio.text;
 </​code>​ </​code>​
  
-==== Get a list of available styles ​====+If you instead want to have the citation string then simply replace the 7th 
 +line with ''​var biblio ​qc.getContentFromItems(items,​ format, null, true);''​. 
 + 
 + 
 +=== Get a list of available styles ===
  
 <code javascript> ​ <code javascript> ​
Line 262: Line 279:
 </​code>​ </​code>​
  
-TODO:  get citations. ​ ​change the style. ​ get stuff in other formats,+TODO:  change the style. ​ get stuff in other formats,
 especially RTF especially RTF
  
Line 336: Line 353:
 =====  Batch Editing ===== =====  Batch Editing =====
  
-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 provides ​a powerful way to script changes to your Zotero library. The common case of search-and-replace is accomplished easily using a basic script ​in the [[#​running_ad_hoc_javascript_in_zotero|JavaScript runner]].
  
 Before proceeding, back up your [[:​zotero_data|Zotero data directory]] 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.
Line 369: Line 386:
  
 https://​api.zotero.org/​itemFields?​pprint=1. https://​api.zotero.org/​itemFields?​pprint=1.
 +
 +==== Example: Creator Name Changes ====
 +
 +Edit the first four lines as necessary:
 +
 +<code javascript>​var oldName = "​Robert L. Smith";​
 +var newFirstName = "​Robert";​
 +var newLastName = "​Smith";​
 +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('​creator',​ '​is',​ oldName);
 +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";</​code>​
  
 ==== Example: Delete Tags By Name ==== ==== Example: Delete Tags By Name ====
dev/client_coding/javascript_api.1560239079.txt.gz · Last modified: 2019/06/11 03:44 by dstillman