This repo is published as an NPM package zotero-plugin-toolkit, which provides useful APIs for Zotero plugin developers.
ZoteroToolkit: Contains all modules of this library. Start from import ZoteroToolkit from "zotero-plugin-toolkit"
to get familiar with the APIs.
Zotero
, ZoteroPane
, window
, document
, and any variables under window
. With type hint.Zotero.debug
and console.log
. Can be customized depending on dev/prod environment.Tools
UI: Create elements and manage them automatically.
Reader: Reader instance APIs.
ExtraField: Get/set extra fields APIs.
Managers
Helpers
Clipboard: Copy text/rich text/image.
FilePicker: Open file picker.
ProgressWindow: Open progress window.
VirtualizedTable: Create a VirtualizedTable (an advanced table view element, which is used by the Zotero item tree, collections tree, item picker, etc.)
Dialog: Create a dialog window(a superset of XUL dialog). With data-binding, auto-layout, and control buttons.
Guide: Create a step-by-step guide.
LargePref: Store/read large data in prefs.js
.
Patch: Patch Zotero's built-in functions. A replacement of PatchManager
.
Utils
zotero://ztoolkit-debug/?file=x.js&run=y()&password=zzz&app=m
See https://github.com/windingwind/zotero-plugin-template/blob/main/scripts/reload.mjs for example.
Parameters (all parameters should be URLEncoded):
- file: the path of JS file to run if provided. starts with
file:///
.- run: the JS script to run if provided.
- password: the value of
extensions.zotero.debug-bridge.password
. If the password is not empty in Zotero and not provided in the call, the command won't run; otherwise a popup will show to ask user if to execute the command.- app: The app name to show in the popup.
zotero://plugin/?action=install&url=x.xpi
Parameters (all parameters should be URLEncoded):
- action:
install
.- url: the url of plugin
xpi
to install.- minVersion: the required minimal version of Zotero if provided.
- maxVersion: the required maximal version of Zotero if provided.
Run npm install --save zotero-plugin-toolkit
.
Import the toolkit class
import { ZoteroToolkit } from "zotero-plugin-toolkit";
/* Alternatively, import class you need to minify the plugin size
* ```ts
* import { BasicTool } from "zotero-plugin-toolkit";
* import { UITool } from "zotero-plugin-toolkit";
*/
const ztoolkit = new ZoteroToolkit();
ztoolkit.log("This is Zotero:", toolkit.getGlobal("Zotero"));
⚠️All Manager classes have
register
method with correspondingunregister/unregisterAll
. Don't forget to unregister when plugin exits.This repo depends on zotero-types. See its hompage for more details about Zotero type definitions.
This package is integrated into the Zotero Plugin Template. You can find examples there.
If you are new to Zotero plugins/looking for solutions to migrate from Zotero 6 to 7, please take a look at that repo.
The API documentation also contains example code for some APIs.
Fork this repo.
Make sure you have nodejs
and npm
installed. Clone the repo folder and install dependencies:
git clone https://github.com/windingwind/zotero-plugin-toolkit
cd zotero-plugin-toolkit
npm install
Run npm run build
.
Package .js
and .d.ts
under ./dist
;
Documentations under ./docs
.
Test it with your plugin or use Zotero Plugin Template as a playground.
Run npm install /path/to/this/repo
under the playground repo folder, the lib will be installed from your local build.
The playground uses the latest build. No need to npm install again if you rebuild this lib.
npm run release
. Tagged pushes will trigger a npm-publish GitHub action.
Use this code under MIT License. No warranties are provided. Keep the laws of your locality in mind!
If you want to change the license, please contact me at wyzlshx@foxmail.com