Zotero Plugin Toolkit

Compile the project by running npm run build. This generates the following outputs:

• JavaScript files (.js) and TypeScript declaration files (.d.ts) in the ./dist directory.
• Documentation files in the ./docs directory.

To get full TypeScript support for Zotero APIs while using the toolkit, install zotero-types as a development dependency.

npm install --save-dev zotero-types

To begin contributing, fork the repository, clone it locally, and install the necessary dependencies using npm. Ensure you have nodejs and npm installed on your system.

git clone https://github.com/windingwind/zotero-plugin-toolkit
cd zotero-plugin-toolkit
npm install

Install the toolkit using your preferred package manager to begin simplifying Zotero plugin development for Zotero 6, 7, and 8.

npm install --save zotero-plugin-toolkit

You can import the toolkit in two ways depending on your bundle size requirements:

1. Full Import: Import the ZoteroToolkit main class to access all modules.
2. Modular Import (Recommended): Import only the specific tools you need (e.g., BasicTool, ClipboardHelper, UITool) to keep your plugin lightweight.

// Option 1: Import all modules via the main class
import { ZoteroToolkit } from "zotero-plugin-toolkit";
const ztoolkit = new ZoteroToolkit();

// Option 2: Import only what you need (Recommended)
import { BasicTool, ClipboardHelper, UITool } from "zotero-plugin-toolkit";
const basic = new BasicTool();
const ui = new UITool();

Install zotero-plugin-toolkit from npm to access a collection of APIs designed for Zotero plugin development.

Compatibility Note:

• Zotero 8 is supported.
• Ensure you use version 5.1.0 or later of the toolkit for Zotero 8 support.

npm install zotero-plugin-toolkit

You can test your local changes by installing the toolkit directly into a Zotero plugin project or a playground.

Using the Zotero Plugin Template as a playground:

1. Build the toolkit using npm run build.
2. In your playground repository folder, run npm install /path/to/this/repo (replacing /path/to/this/repo with the actual local path to the toolkit).

The playground will use your local build. If you rebuild the toolkit, the playground will automatically use the updated version without needing to run npm install again.

The UITool class provides a high-level API for creating, managing, and automatically cleaning up DOM elements (HTML, XUL, and SVG).

In bootstrap plugins, elements added to the Zotero UI must be manually removed when the plugin exits to prevent memory leaks or UI clutter. UITool solves this by maintaining an internal elementCache. When you call unregisterAll(), all elements created via createElement (that have enableElementRecord set to true, which is the default) are automatically removed from the DOM.

Key lifecycle methods:

• unregisterAll(): Removes all elements tracked by the toolkit instance.

// Example of automatic cleanup
const ui = new UITool(options);
const myDiv = ui.createElement(document, "div", { id: "my-plugin-div" });

// Later, when the plugin is disabling/exiting:
ui.unregisterAll(); // myDiv is automatically removed from the DOM