Zotero Plugin Toolkit

Intro

This repo is published as an NPM package zotero-plugin-toolkit, which provides useful APIs for Zotero plugin developers.

API Documentation

Modules

• ZoteroToolkit: Contains all modules of this library. Start from import ZoteroToolkit from "zotero-plugin-toolkit" to get familiar with the APIs.

• Basic Tool

  • getGlobal: Get global variables for bootstrapped plugin sandbox. Zotero, ZoteroPane, window, document, and any variables under window. With type hint.
  • log: Output to both Zotero.debug and console.log. Can be customized depending on dev/prod environment.
  • createXULElement/getDOMParser: Compatible on Zotero 6 & 7+. See https://www.zotero.org/support/dev/zotero_7_for_developers

• Tools

  • UI: Create elements and manage them automatically.

  • Reader: Reader instance APIs.

  • ExtraField: Get/set extra fields APIs.

• Managers

  • Menu: Register menu/menu popup.

  • Keyboard: Register keyboard shortcuts.

  • FieldHook: Register custom fields.

  • Prompt: Register prompt panel command.

• 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

  • Debug Bridge: Use 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.

  • Plugin Bridge: Use 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.

  • Wait: Wait for a condition to be true.

Usage

1. Run npm install --save zotero-plugin-toolkit.

2. 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();

3. Use the toolkit following this API Documentation

ztoolkit.log("This is Zotero:", toolkit.getGlobal("Zotero"));

⚠️All Manager classes have register method with corresponding unregister/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.

Examples

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.

Contributing

Setup

1. Fork this repo.

2. 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

Build

Run npm run build.

• Package .js and .d.ts under ./dist;

• Documentations under ./docs.

Test Locally

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.

Release

npm run release. Tagged pushes will trigger a npm-publish GitHub action.

Disclaimer

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 [email protected]