This is a plugin template for Zotero. Plugins using this template are shown above.
📖Plugin Development Documentation(Chinese, provides English translation)
🛠️Zotero Plugin Toolkit | API Documentation
📌Zotero Plugin Template(This repo)
👍You are currently in
bootstrap
extension mode. To useoverlay
mode, plsase switch tooverlay
branch in git.
👁 Watch this repo so that you can be notified whenever there are fixes & updates.
- Event-driven, functional programming, under extensive skeleton;
- Simple and user-friendly, works out-of-the-box.
- Abundant examples in
src/modules/examples.ts
, covering most of the commonly used APIs in plugins(using zotero-plugin-toolkit); - TypeScript support:
- Full type definition support for the whole Zotero project, which is written in JavaScript(using zotero-types);
- Global variables and environment setup;
- Plugin build/test/release workflow:
- Automatically generate/update plugin id/version, update configrations, and set environment variables(
development/production
); - Automatically build and reload code in Zotero;
- Automatically release to GitHub(using release-it);
- Automatically generate/update plugin id/version, update configrations, and set environment variables(
- ⭐[New!]Compatibilities for Zotero 6 & Zotero 7.(using zotero-plugin-toolkit)
This repo provides examples for zotero-plugin-toolkit APIs.
Search @example
in src/examples.ts
. The examples are called in src/hooks.ts
.
- registerNotifier
- registerPrefs, unregisterPrefs
- registerShortcuts
- exampleShortcutLargerCallback
- exampleShortcutSmallerCallback
- exampleShortcutConflictionCallback
- registerStyleSheet(the official make-it-red example)
- registerRightClickMenuItem
- registerRightClickMenuPopup
- registerWindowMenuWithSeprator
- registerExtraColumn
- registerExtraColumnWithCustomCell
- registerCustomCellRenderer
- registerLibraryTabPanel
- registerReaderTabPanel
- unregisterUIExamples
- Fork this repo;
- Git clone the forked repo;
- Enter the repo folder;
- Modify the settings in
./package.json
, including:
version,
author,
description,
homepage,
config {
releasepage,
updaterdf,
addonName,
addonID,
addonRef
}
Be careful to set the addonID and addonRef to avoid confliction.
- Run
npm install
to set up the plugin and install dependencies. If you don't have NodeJS installed, please download it here; - Run
npm run build
to build the plugin in production mode. Runnpm run build-dev
to build the plugin in development mode. The xpi for installation and the built code is underbuilds
folder.
What the difference between dev & prod?
- This environment variable is stored in
Zotero.AddonTemplate.data.env
. The outputs to console is disabled in prod mode.- You can decide what users cannot see/use based on this variable.
See also
src/hooks.ts
- 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 fromindex.ts
) - Register resources if Zotero 7+
- In the main entrance
index.js
, the plugin object is injected underZotero
andhooks.ts
>onStartup
is called.- Initialize anything you want, including notify listeners, preference panes, and UI elements.
- 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.
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;
Zotero 6 doesn't support preference pane injection in bootstrap mode, thus I write a register for Zotero 6 or lower.
You only need to maintain one preferences.xhtml
which runs natively on Zotero 7 and let the plugin template handle it when it is running on Zotero 6.
![]() Zotero 7
|
![]() Zotero 6
|
zotero-plugin-template/src/modules/examples.ts
Lines 73 to 85 in 08d72a4
<preferences>
element is deprecated. Please use the full pref-key in the elements'preference
attribute. Like:
<checkbox label="&zotero.__addonRef__.pref.enable.label;" preference="extensions.zotero.__addonRef__.enable" />
The elements with preference
attributes will bind to Zotero preferences.
Remember to call unregister()
on plugin unload.
The plugin template provides new APIs for bootstrap plugins. We have two reasons to use these APIs, instead of the createElement/createElementNS
:
- In bootstrap mode, plugins have to clean up all UI elements on exit (disable or uninstall), which is very annoying. Using the
createElement
, the plugin template will maintain these elements. Justunregister
on exit. - Zotero 7 requires createElement()/createElementNS() → createXULElement() for remaining XUL elements, while Zotero 6 doesn't support
createXULElement
. UsingcreateElement
, it switches API depending on the current platform automatically.
There are more advanced APIs for creating elements in batch: creatElementsFromJSON
. Input an element tree in JSON and return a fragment/element. These elements are also maintained by this plugin template.
This section shows the directory structure of a template.
- All
.js/.ts
code files are in./src
; - Addon config files:
./addon/chrome.manifest
,./addon/install.rdf
, and./addon/manifest.json
; - UI files:
./addon/chrome/content/*.xhtml
. - Locale files:
./addon/chrome/locale/[*.dtd, *.properties]
; - Resource files:
./addon/chrome/skin/default/__addonRef__/*.dtd
; - Preferences file:
./addon/chrome/defaults/preferences/defaults.js
;Don't break the lines in the
defaults.js
│ .gitignore
│ .release-it.json # release-it conf
| tsconfig.json # https://code.visualstudio.com/docs/languages/jsconfig#
│ build.js # esbuild
│ LICENSE
│ package.json # npm conf
│ README.md # readme
│ update.rdf # addon update
│
├─.github # github conf
│
├─addon # addon dir
│ │ chrome.manifest # for Zotero 6
│ │ manifest.json # for Zotero 7
│ │ install.rdf # addon install conf, for Zotero 6
│ │ bootstrap.js # addon load/unload script, like a main.c
│ │
│ └─chrome
│ ├─content # UI
│ │ │ preferences.xhtml
│ │ │
│ │ ├─icons
│ │ │ favicon.png
│ │ │ favicon@0.5x.png
│ │ │
│ │ └─scripts
│ └─locale # locale
│ ├─en-US
│ │ overlay.dtd
│ │ addon.properties
│ │
│ ├─zh-CN
│ | overlay.dtd
│ └─ addon.properties
│
├─builds # build dir
│ └─.xpi
│
└─src # source code
│ index.ts # main entry
│ addon.ts # base class
│ hooks.ts # lifecycle hooks
|
└─modules # sub modules
│ examples.ts # examples factory
│ locale.ts # locale .properties
│ preferenceScript.ts # script runs in preferences.xhtml
└─ progressWindow.ts # progressWindow tool
# A release-it command: version increase, npm run build, git push, and GitHub release
# You need to set the environment variable GITHUB_TOKEN https://github.com/settings/tokens
# release-it: https://github.com/release-it/release-it
npm run release
Alternatively, build it directly using build.js: npm run build
- Clean
./builds
- Copy
./addon
to./builds
- Esbuild to
./builds/addon/chrome/content/scripts
- Replace
__buildVersion__
and__buildTime__
in./builds/addon
- Zip the
./builds/addon
to./builds/*.xpi
- Copy zotero command line config file. Modify the commands.
cp ./scripts/zotero-cmd-default.json ./scripts/zotero-cmd.json
vim ./scripts/zotero-cmd.json
-
Setup plugin development environment following this link.
-
Build plugin and restart Zotero with this npm command.
-
Launch Firefox 60
-
In Firefox, go to devtools, go to settings, click "enable remote debugging" and the one next to it that's also about debugging(or press
shift+F8
). -
In Zotero, go to setting, advanced, config editor, look up "debugging" and click on "allow remote debugging"
-
In Firefox, click the hamburger menu in the top right -> web developer -> Connect...
-
Enter localhost:6100
-
Connect
-
Click "Inspect Main Process"
npm run restart
You can also debug code in these ways:
- Test code segments in Tools->Developer->Run Javascript;
- Debug output with
Zotero.debug()
. Find the outputs in Help->Debug Output Logging->View Output; - UI debug. Zotero is built on the Firefox XUL framework. Debug XUL UI with software like XUL Explorer.
XUL Documents:
https://www.xul.fr/tutorial/
http://www.xulplanet.com/
Search for a Zotero API
Zotero docs are outdated or incomplete. Searching the source code of Zotero is unavoidable.
Clone https://github.com/zotero/zotero and search the keyword globally. You can search the UI text in .xul
/.dtd
files, and then search the keys of the text value in .js
/.xul
files.
⭐The zotero-types provides most frequently used Zotero APIs. It's included in this template by default.
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
Part of the code of this repo refers to other open-source projects within the allowed scope.
- zotero-better-bibtex(
d.ts
)