Home

Awesome

Zotero Plugin Template

zotero target version Using Zotero Plugin Template

This is a plugin template for Zotero.

English | ็ฎ€ไฝ“ไธญๆ–‡

[!tip] ๐Ÿ‘ Watch this repo so that you can be notified whenever there are fixes & updates.

Plugins built with this template

GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars GitHub Repo stars

If you are using this repo, I recommended that you put the following badge on your README:

Using Zotero Plugin Template

[![Using Zotero Plugin Template](https://img.shields.io/badge/Using-Zotero%20Plugin%20Template-blue?style=flat-square&logo=github)](https://github.com/windingwind/zotero-plugin-template)

Features

Examples

This repo provides examples for zotero-plugin-toolkit APIs.

Search @example in src/examples.ts. The examples are called in src/hooks.ts.

Basic Examples

Shortcut Keys Examples

UI Examples

image

Preference Pane Examples

image

See src/modules/preferenceScript.ts

HelperExamples

image

PromptExamples

An Obsidian-style prompt(popup command input) module. It accepts text command to run callback, with optional display in the popup.

Activate with Shift+P.

image

Quick Start Guide

0 Requirement

  1. Install a beta version of Zotero: https://www.zotero.org/support/beta_builds
  2. Install Node.js and Git

[!note] This guide assumes that you have an initial understanding of the basic structure and workings of the Zotero plugin. If you don't, please refer to the documentation and official plugin examples Make It Red first.

1 Creat Your Repo

  1. Click Use this template

  2. Git clone your new repo

    <details > <summary>๐Ÿ’ก Start with GitHub Codespace</summary>

    GitHub CodeSpace enables you getting started without the need to download code/IDE/dependencies locally.

    Replace the steps above and build you first plugin in 30 seconds!

    • Goto top of the homepage, click the green button Use this template, click Open in codespace. You may need to login to your GitHub account.
    • Wait for codespace to load.
    </details>

  3. Enter the repo folder

2 Config Template Settings and Enviroment

  1. Modify the settings in ./package.json, including:

    {
  version: "", // to 0.0.0
  author: "",
  description: "",
  homepage: "",
  config: {
    addonName: "", // name to be displayed in the plugin manager
    addonID: "", // ID to avoid conflict. IMPORTANT!
    addonRef: "", // e.g. Element ID prefix
    addonInstance: "", // the plugin's root instance: Zotero.${addonInstance}
    prefsPrefix: "extensions.zotero.${addonRef}", // the prefix of prefs
  },
}

    [!warning] Be careful to set the addonID and addonRef to avoid conflict.

    If you need to host your XPI packages outside of GitHub, moidify updateURL and add xpiDownloadLink in zotero-plugin.config.ts.

  2. Copy the environment variable file. Modify the commands that starts your installation of the beta Zotero.

    Create a development profile (Optional)
    Start the beta Zotero with /path/to/zotero -p. Create a new profile and use it as your development profile. Do this only once

    cp .env.example .env
vim .env

    If you are developing more than one plugin, you can store the bin path and profile path in the system environment variables, which can be omitted here.

  3. Install dependencies with npm install

    If you are using pnpm as the package manager for your project, you need to add public-hoist-pattern[]=*@types/bluebird* to .npmrc, see https://github.com/windingwind/zotero-types?tab=readme-ov-file#usage.

    If you get npm ERR! ERESOLVE unable to resolve dependency tree with npm install, which is an upstream dependency bug of typescript-eslint, use the npm i -f command to install it.

3 Coding

Start development server with npm start, it will:

Auto Hot Reload

Tired of endless restarting? Forget about it!

  1. Run npm start.
  2. Coding. (Yes, that's all)

When file changes are detected in src or addon, the plugin will be automatically compiled and reloaded.

<details style="text-indent: 2em"> <summary>๐Ÿ’ก Steps to add this feature to an existing plugin</summary>

Please see zotero-plugin-scaffold.

</details>

Debug in Zotero

You can also:

4 Build

Run npm run build to build the plugin in production mode, and the xpi for installation and the built code is under build folder.

Steps of build:

[!note]

What's the difference between dev & prod?

5 Release

To build and release, use

# version increase, git add, commit and push
# then on ci, npm run build, and release to GitHub
npm run release

[!note] This will use Bumpp to prompt for the new version number, locally bump the version, run any (pre/post)version scripts defined in package.json, commit, build (optional), tag the commit with the version number and push commits and git.tags. Bumpp can be configured in zotero-plugin-config.ts; for example, add release: { bumpp: { execute: "npm run build" } } to also build before committing.

Subsequently GitHub Action will rebuild the plugin and use zotero-plugin-scaffold's release script to publish the XPI to GitHub Release. In addition, a separate release (tag: release) will be created or updated that includes update manifests update.json and update-beta.json as assets. These will be available at https://github.com/{{owner}}/{{repo}}/releases/download/release/update*.json.

About Prerelease

The template defines prerelease as the beta version of the plugin, when you select a prerelease version in Bumpp (with - in the version number). The build script will create a new update-beta.json for prerelease use, which ensures that users of the regular version won't be able to update to the beta. Only users who have manually downloaded and installed the beta will be able to update to the next beta automatically.

When the next regular release is updated, both update.json and update-beta.json will be updated (on the special release release, see above) so that both regular and beta users can update to the new regular release.

[!warning] Strictly, distinguishing between Zotero 6 and Zotero 7 compatible plugin versions should be done by configuring applications.zotero.strict_min_version in addons.__addonID__.updates[] of update.json respectively, so that Zotero recognizes it properly, see https://www.zotero.org/support/dev/zotero_7_for_developers#updaterdf_updatesjson.

Details

About Hooks

See also src/hooks.ts

  1. When install/enable/startup triggered from Zotero, bootstrap.js > startup is called
    • Wait for Zotero ready
    • Load index.js (the main entrance of plugin code, built from index.ts)
    • Register resources if Zotero 7+
  2. In the main entrance index.js, the plugin object is injected under Zotero and hooks.ts > onStartup is called.
    • Initialize anything you want, including notify listeners, preference panes, and UI elements.
  3. When uninstall/disabled triggered from Zotero, bootstrap.js > shutdown is called.
    • events.ts > onShutdown is called. Remove UI elements, preference panes, or anything created by the plugin.
    • Remove scripts and release resources.

About Global Variables

See also src/index.ts

The bootstrapped plugin runs in a sandbox, which does not have default global variables like Zotero or window, which we used to have in the overlay plugins' window environment.

This template registers the following variables to the global scope:

Zotero, ZoteroPane, Zotero_Tabs, window, document, rootURI, ztoolkit, addon;

Create Elements API

The plugin template provides new APIs for bootstrap plugins. We have two reasons to use these APIs, instead of the createElement/createElementNS:

createElement(document, "div"); // returns HTMLDivElement
createElement(document, "hbox"); // returns XUL.Box
createElement(document, "button", { namespace: "xul" }); // manually set namespace. returns XUL.Button

About Zotero API

Zotero docs are outdated and incomplete. Clone https://github.com/zotero/zotero and search the keyword globally.

โญThe zotero-types provides most frequently used Zotero APIs. It's included in this template by default. Your IDE would provide hint for most of the APIs.

A trick for finding the API you want:

Search the UI label in .xhtml/.flt files, find the corresponding key in locale file. Then search this keys in .js/.jsx files.

Directory Structure

This section shows the directory structure of a template.

.
|-- .github/                  # github conf
|-- .vscode/                  # vscode conf
|-- addon                     # static files
|   |-- bootstrap.js
|   |-- content
|   |   |-- icons
|   |   |   |-- favicon.png
|   |   |   `-- favicon@0.5x.png
|   |   |-- preferences.xhtml
|   |   `-- zoteroPane.css
|   |-- locale
|   |   |-- en-US
|   |   |   |-- addon.ftl
|   |   |   |-- mainWindow.ftl
|   |   |   `-- preferences.ftl
|   |   `-- zh-CN
|   |       |-- addon.ftl
|   |       |-- mainWindow.ftl
|   |       `-- preferences.ftl
|   |-- manifest.json
|   `-- prefs.js
|-- build                         # build dir
|-- node_modules
|-- src                           # source code of scripts
|   |-- addon.ts                  # base class
|   |-- hooks.ts                  # lifecycle hooks
|   |-- index.ts                  # main entry
|   |-- modules                   # sub modules
|   |   |-- examples.ts
|   |   `-- preferenceScript.ts
|   `-- utils                 # utilities
|       |-- locale.ts
|       |-- prefs.ts
|       |-- wait.ts
|       |-- window.ts
|       `-- ztoolkit.ts
|-- typings                   # ts typings
|   `-- global.d.ts

|-- .env                      # enviroment config (do not check into repo)
|-- .env.example              # template of enviroment config, https://github.com/northword/zotero-plugin-scaffold
|-- .gitignore                # git conf
|-- .gitattributes            # git conf
|-- .prettierrc               # prettier conf, https://prettier.io/
|-- eslint.config.mjs         # eslint conf, https://eslint.org/
|-- LICENSE
|-- package-lock.json
|-- package.json
|-- tsconfig.json             # typescript conf, https://code.visualstudio.com/docs/languages/jsconfig
|-- README.md
`-- zotero-plugin.config.ts   # scaffold conf, https://github.com/northword/zotero-plugin-scaffold

Disclaimer

Use this code under AGPL. 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