windingwind/zotero-plugin-template

A plugin template for Zotero.

Zotero Plugin Template

This is a plugin template for Zotero.

English | 简体中文

📖 Plugin Development Documentation (Chinese, outdated)

📖 Plugin Development Documentation for Zotero 7

🛠️ Zotero Plugin Toolkit | API Documentation

ℹ️ Zotero Type Definitions

📜 Zotero Source Code

📌 Zotero Plugin Template (This repo)

Tip

👁 Watch this repo so that you can be notified whenever there are fixes & updates.

Plugins built with this template

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

[![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

• Event-driven, functional programming, under extensive skeleton;
• Simple and user-friendly, works out-of-the-box.
• ⭐ [New!] Auto hot reload! Whenever the source code is modified, automatically compile and reload. See here→
• 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 develop/build/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;
• Prettier and ES Lint integration.

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

• registerNotifier
• registerPrefs, unregisterPrefs

Shortcut Keys Examples

• registerShortcuts
• exampleShortcutLargerCallback
• exampleShortcutSmallerCallback
• exampleShortcutConflictionCallback

UI Examples

• registerStyleSheet(the official make-it-red example)
• registerRightClickMenuItem
• registerRightClickMenuPopup
• registerWindowMenuWithSeprator
• registerExtraColumn
• registerExtraColumnWithCustomCell
• registerCustomItemBoxRow
• registerLibraryTabPanel
• registerReaderTabPanel

Preference Pane Examples

• Preferences bindings
• UI Events
• Table
• Locale

See src/modules/preferenceScript.ts

HelperExamples

• dialogExample
• clipboardExample
• filePickerExample
• progressWindowExample
• vtableExample(See Preference Pane Examples)

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.

• registerAlertPromptExample

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

   💡 Start with GitHub Codespace

   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.

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:

• Prebuild the plugin in development mode
• Start Zotero with plugin loaded from build/
• Watch src/** and addon/**.
  • If src/** changed, run esbuild and reload
  • If addon/** has changed, rebuild the plugin (in development mode) and reload

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.

💡 Steps to add this feature to an existing plugin

Please see zotero-plugin-scaffold.

Debug in Zotero

You can also:

• Test code snippets in Tools -> Developer -> Run Javascript;
• Debug output with Zotero.debug(). Find the outputs in Help->Debug Output Logging->View Output;
• Debug UI. Zotero is built on the Firefox XUL framework. Debug XUL UI with software like XUL Explorer.

  XUL Documentation: http://www.devdoc.net/web/developer.mozilla.org/en-US/docs/XUL.html

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:

• Create/empty build/.
• Copy addon/** to build/addon/**
• Replace placeholders: use replace-in-file to replace keywords and configurations defined in package.json in non-build files (xhtml, json, et al.).
• Prepare locale files to avoid conflict
  • Rename **/*.flt to **/${addonRef}-*.flt
  • Prefix each fluent message with addonRef-
• Use ESBuild to build .ts source code to .js, build src/index.ts to ./build/addon/chrome/content/scripts.
• (Production mode only) Zip the ./build/addon to ./build/*.xpi
• (Production mode only) Prepare update.json or update-beta.json

Note

What's the difference between dev & prod?

• This environment variable is stored in Zotero.${addonInstance}.data.env. The outputs to console is disabled in prod mode.
• You can decide what users cannot see/use based on this variable.
• In production mode, the build script will pack the plugin and update the update.json.

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

In this template, release-it is configured to locally bump the version, build, and push commits and git.tags, subsequently GitHub Action will rebuild the plugin and publish the XPI to GitHub Release.

About Prerelease

The template defines prerelease as the beta version of the plugin, when you select a prerelease version in release-it (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 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:

• 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. Just unregisterAll at the exit.
• Zotero 7 requires createElement()/createElementNS() → createXULElement() for remaining XUL elements, while Zotero 6 doesn't support createXULElement. The React.createElement-like API createElement detects namespace(xul/html/svg) and creates elements automatically, with the return element in the corresponding TS element type.

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.

• All .js/.ts code files are in ./src;
• Addon config files: ./addon/manifest.json;
• UI files: ./addon/chrome/content/*.xhtml.
• Locale files: ./addon/locale/**/*.flt;
• Preferences file: ./addon/prefs.js;

  Don't break the lines in the prefs.js

.
|-- .eslintrc.json            # eslint conf
|-- .gitattributes            # git conf
|-- .github/                  # github conf
|-- .gitignore                # git conf
|-- .prettierrc               # prettier conf
|-- .release-it.json          # release-it conf
|-- .vscode                   # vs code conf
|   |-- extensions.json
|   |-- launch.json
|   |-- setting.json
|   `-- toolkit.code-snippets
|-- package-lock.json         # npm conf
|-- package.json              # npm conf
|-- LICENSE
|-- README.md
|-- addon
|   |-- bootstrap.js               # addon load/unload script, like a main.c
|   |-- chrome
|   |   `-- content
|   |       |-- icons/
|   |       |-- preferences.xhtml  # preference panel
|   |       `-- zoteroPane.css
|   |-- locale                     # locale
|   |   |-- en-US
|   |   |   |-- addon.ftl
|   |   |   `-- preferences.ftl
|   |   `-- zh-CN
|   |       |-- addon.ftl
|   |       `-- preferences.ftl
|   |-- manifest.json              # addon config
|   `-- prefs.js
|-- build/                         # build dir
|-- scripts                        # scripts for dev
|   |-- build.mjs                      # script to build plugin
|   |-- scripts.mjs                    # scripts send to Zotero, such as reload, openDevTool, etc
|   |-- server.mjs                     # script to start a development server
|   |-- start.mjs                      # script to start Zotero process
|   |-- stop.mjs                       # script to kill Zotero process
|   |-- utils.mjs                      # utils functions for dev scripts
|   |-- update-template.json      # template of `update.json`
|   `-- zotero-cmd-template.json  # template of local env
|-- src                           # source code
|   |-- 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
|-- tsconfig.json                 # https://code.visualstudio.com/docs/languages/jsconfig
|-- typings                       # ts typings
|   `-- global.d.ts
`-- update.json

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

zotero-plugin-template's Issues

Plugins error if using node built-ins

I'm trying to make a plugin, but it relies on spawning a child process to manage some stuff on the command line. The building process seems to work fine, but it seems like Zotero can't handle some modules

This test code:

Results in this error:

Due to this line in the built code:

I think it's an issue with modules built in to node, but I'm not sure if that's the issue, and I'm also unsure how to solve this (JS isn't my area of expertise so apologies if any of this is incorrect/obvious to fix!)

multiline editable custom field

Hi, is it possible to register an editable custom field with mutiple lines (allowing line breaks)?
Thanks for your help in advance.

How to access Zotero Items in a hierarchical manner?

I'm building a private cloud for my zotero, and was wondering how to access the files in a hierarchical way?
E.x. looking at the following image, I'd like to have some sort of indication that the attachment "reddit post snapshot" is a child of the item "an incredible workflow".

To my knowledge Zotero.Items currently just gives a flattened list of items.

Initial clone + build fails on module resolution for `zotero-types`

Hi, I'm following the template instructions step-by-step. Pardon my basic questions; I am not familiar with esbuild.

I have:

1. cloned the respository
2. modified package.json
3. run npm install
4. run npm run build

at which point, the build fails with these errors:

[Build] BUILD_DIR=builds, VERSION=0.0.0, BUILD_TIME=2022-08-31 10:26:14
✘ [ERROR] Could not resolve "zotero-types"

    src/index.ts:1:23:
      1 │ import { Zotero } from "zotero-types";
        ╵                        ~~~~~~~~~~~~~~

  You can mark the path "zotero-types" as external to exclude it from the bundle, which will remove
  this error.

✘ [ERROR] Could not resolve "zotero-types"

    src/views.ts:1:28:
      1 │ import { XUL, Zotero } from "zotero-types";
        ╵                             ~~~~~~~~~~~~~~

  You can mark the path "zotero-types" as external to exclude it from the bundle, which will remove
  this error.

✘ [ERROR] Could not resolve "zotero-types"

    src/events.ts:1:23:
      1 │ import { Zotero } from "zotero-types";
        ╵                        ~~~~~~~~~~~~~~

  You can mark the path "zotero-types" as external to exclude it from the bundle, which will remove
  this error.

Additional information:

• zotero-types exists in node_modules, among 348 total folders in node_modules following npm install. zotero-types contains README.md, package.json, and index.d.ts
• following the error message, I modify build.js this way:

await esbuild
  .build({
    entryPoints: ["src/index.ts"],
    external: ["zotero-types"],       // <--- add this line
    bundle: true,
    // Entry should be the same as add ...
    outfile: path.join(buildDir, "addo ...
    // minify: true,                  
  })
  .catch(() => process.exit(1));      

and it appears to build ok. Is this the correct fix?

system information

[nix-shell:/tmp/zotero-addon-template]$ echo $NODE_PATH
/tmp/zotero-addon-template/node_modules

[nix-shell:/tmp/zotero-addon-template]$ node --version
v18.7.0

[nix-shell:/tmp/zotero-addon-template]$ npm --version
8.15.0

thank you for your work

'keyOptions.keyboard' is possibly 'undefined'.

Trying to set up a basic new plugin by following the instructions. When I do a npm run build, I get the following error:

'keyOptions.keyboard' is possibly 'undefined'.

Any ideas? Am not too familiar with JS/TS development.

Use react for plugin development

Hi, I have seen some Zotero plugins built with React: https://github.com/diegodlh/zotero-cita

Is it supported by zotero-plugin-template? Thanks!

Zotero Fails to Recognize Available Updates for the Plugin

Hi,

I am using your template to create my own Zotero Addon, but I am facing a problem with the auto-update.
Maybe you have time to have a look: themetalleg/greatify#9

Best

Does preferences.xul create a preference pane?

Testing out this repository from scratch:

1. clone repository (bootstrap branch)
2. npm install
3. npm run build
4. manually install the xpi into Zotero

Everything works smoothly. After installation, right-clicking on an entry shows the Zotero Template menu item; clicking the menu item shows an alert box with "Hello World". Is this the full extent of the example?

I trying to see if I can add a preferences pane into the main Preferences window (Edit -> Preferences). I realize this is an XUL method and may be phased out in Zotero 7, but I don't see another way to do it, and your repository does add it to the XPI bundle.

Reading the XUL file seems to imply that it should show up, but it doesn't. Can you clarify this for me?

Also, in the current xul file https://github.com/windingwind/zotero-addon-template/blob/bootstrap/addon/chrome/content/preferences.xul#L9 there are many attributes with spaces in them. I don't know if this affects functionality at all; FWIW, I removed all extra spaces and nothing changed.

Thank you

How to upgrade

Hi,
I'm using an older version of this template. What would be the best way to upgrade? Or isn't that really necessary?

Errors after I install the template xpi

Hello Windingwind,

I'm new to build the plugins and I found your significant contribution in this area and thanks for providing such a comprehensive guide, but I just came into some problems here.
I'm using Apple Silicon Zotero 7 the latest build to test the plugin template for the first time. After I successfully compiled, I was installing the xpi file via the GUI of Zotero 7. However, the Zotero Addon Template is showing the Addon is loading to 30% and stopped moving.
Then I opened the error console, it shows that

• Uncaught (in promise) undefined 2
• TypeError: this.globalCache is undefined [addontemplate.js:1597:15]
• TypeError: this.gViewSourceUtils is undefined5 webconsole.js:225:5
  viewSource resource://devtools/client/webconsole/webconsole.js:225
  onViewSource resource://devtools/client/webconsole/service-container.js:43
  onClick resource://devtools/client/shared/components/Frame.js:259
  React 19
  dispatchInteractiveEvent self-hosted:1162

Would you have any idea what's the root cause and how to fix it?

Thanks
pjnkun

getString("addon-static-example", { branch: "branch-example" })

getString("addon-static-example", { branch: "branch-example" }) 获取分支配置时返回的时array，这里建立增加对数组的判断，提升兼容性。

function _getString(
  localeString: string,
  options: { branch?: string | undefined; args?: Record<string, unknown> } = {},
): string {
  const localStringWithPrefix = `${config.addonRef}-${localeString}`;
  const { branch, args } = options;
  const pattern = addon.data.locale?.current.formatMessagesSync([
    { id: localStringWithPrefix, args },
  ])[0];
  if (!pattern) {
    return localStringWithPrefix;
  }
  if (branch && pattern.attributes) {
    for (const attr of pattern.attributes) {
      if (attr.name === branch) {
        return attr.value
      }
    }
    return pattern.attributes[branch] || localStringWithPrefix;
  } else {
    return pattern.value || localStringWithPrefix;
  }
}

The build doesn't use typescript type-checking

esbuild doesn't do anything with typescript except strip it down to javascript while bundling. To get the benefits of typescript, we'd need to run tsc --noEmit and/or eslint in parallel with build.js. To do this in a cross-platform way would require the use of worker_threads. For linux/macos it'd be easy to do using GNU parallel, but on windows this requires installing git-bash (which may be a reasonable ask, I don't use windows though).

[Announcement] Change to Bootstraped Extension

I plan to add a new branch bootstrap to this template and make it a bootstraped extension, which will be set the main branch after finish, for the overlay extension will no longer be supported in the coming Zotero 7.

See discussion here: https://groups.google.com/g/zotero-dev/c/TT_rcLVpQwg/m/qGgqzCfvAQAJ

If you are using the overlay mode, don't worry. Won't be too hard to migrate to bootstrap mode.

Also plan to wrap some important overlay functions, like right-click menu, pref-window, etc. as a new npm package

Changing Report Look

Hi, is there at the moment a way to change the look of the reports? To include costum fields for example or show images? I was not able to find anything in the documentation.

Table disappears when open preference window the second time

I built the latest version locally and import the demo plugin into my Zotero, it seems work well. When I open the preference window, I could see the preference table perfectly. However, after closing the preference window and reopen i, I found that the preference table disappear, no matter how many times I reopen the window.

This is what I saw when open the window for the first time:

When I open the preference window for the second time, the table disappears:

How would you add a radio button?

I've tried adding a radio button group to the preferences, but I've had no success so far... Could you provide an example?

zotero not able to find the boostrap methods

Still having some problems getting the examples running. When I enable/disable the plugin in Zotero, the console says that it can't find the bootstrap methods for startup & shutdown. No doubt I've done something wrong here in my repo?

Thx.

oncommand vs commandListener

Hi, I'm trying to understand how this template works. My TS/JS knowledge is limited so it's not so easy for me.

What is the difference between oncommand, and commandListener? Are there recommendations which one should be used?

E.g., I have this:

export class TestUI{

  static registerRightClickMenuPopup() {
    ztoolkit.Menu.register(
      "item",
      {
        tag: "menu",
        label: getString("menupopup-label"),
        children: [
          {
            tag: "menuitem",
            label: getString("menuitem-test1"),
            oncommand: "alert('asdf')",
          },
          {
            tag: "menuitem",
            label: getString("menuitem-test2"),
            commandListener: () => test(),
          },
          {
            tag: "menuitem",
            label: getString("menuitem-test3"),
            oncommand: "test()",
          },
        ],
      },
      "before",
      document.querySelector(
        "#zotero-itemmenu-addontemplate-test",
      ) as XUL.MenuItem,
    );
  }

function test() {
  //alert('Hi'); //alert does not seem to be in scope here...
  ztoolkit.getGlobal("alert")("Hi");
}

Calling the function test with commandListener works, but not with oncommand. Also, alert works when used directly on oncommand, but not inside a function. Why is that?

Question on Zotero Version Requirement

Thanks for creating this template which I found immensely useful.

Some of my users have experienced version compatibility issue, such as: lifan0127/ai-research-assistant#16

Do you have any insight/guidance?

Issue with Zotero 6 + bootstrap plugin

          @northword @windingwind  我现在在用zotero6 bootstrap, 尝试开发插件, 但是使用模板build 的xpi插件不起作用, 我只改了package.json里面的name 和id, 下面是zotero 启动后打印出来的debug log, 请问下是什么原因导致的 

debug log(zotero 6):

[JavaScript Error: "expected expression, got '.'" {file: "resource://gre/modules/addons/XPIProvider.jsm -> jar:file:///home/madhouse/.zotero/zotero/9nlboxq4.default/extensions/[email protected]!/bootstrap.js -> jar:file:///home/madhouse/.zotero/zotero/9nlboxq4.default/extensions/[email protected]!/chrome/content/scripts/index.js" line: 5877 column: 31 source: "      return addon.data.locale?.stringBundle.GetStringFromName(localString);
"}]
startup@resource://gre/modules/addons/XPIProvider.jsm -> jar:file:///home/madhouse/.zotero/zotero/9nlboxq4.default/extensions/[email protected]!/bootstrap.js:99:3

我目前想要开发的功能是可以通过pdf的注释添加引用后, 直接链接跳转到另一个pdf的注释页面(引文的页面), 网上好像没有人做这个功能, 要不就不会这么伤脑筋了.

Originally posted by @YaoLiMuMu in #96 (comment)

Unit tests with zotero-plugin-template

May I ask for your advice on how to incorporate unit tests in Zotero plugin development? I couldn't find any reference in the zotero-plugin-template documentation.

Separately I see how zotero-better-bibtext set up tests which is quite complicated: https://github.com/retorquere/zotero-better-bibtex/blob/master/test/behave

Do you have any guidance? Thank you!

killZoteroUnix should ignore grep process

Thank you for making this amazing template. It's a remarkable contribution. It's amazingly extensive and clear.

A fairly minor thing, but on nix systems, the current kill command tries to kill the grep process that it calls in the pipe.

I've been using kill -9 $(ps -x | grep '[z]otero' | awk '{print $1}') to only capture the zotero process and ignore the grep command. Does it make sense to update killZoteroUnix in zotero-cmd-template.json?

(If it makes sense to update the command and you'd like me to open a PR for that file, let me know).

Plugin built from source is not compatible with zotero7beta

Hi, I'm following the instructions in “Build From Source”. But the plugin is not compatible with Zotero.

npm run build-dev

> [email protected] build-dev
> cross-env NODE_ENV=development node scripts/build.mjs

(node:3656) ExperimentalWarning: Import assertions are not a stable feature of the JavaScript language. Avoid relying on their current behavior and syntax as those might change in a future 
version of Node.js.
(Use `node --trace-warnings ...` to show where the warning was created)
(node:3656) ExperimentalWarning: Importing JSON modules is an experimental feature and might change at any time
[Build] BUILD_DIR=builds, VERSION=0.1.6, BUILD_TIME=2023-06-09 22:41:30, ENV=development
[Build] Run esbuild OK
[Build] Run replace in  [ 'update.json : 5 / 5', 'update.rdf : 4 / 4' ]
[Build] Replace OK
[Build] Addon prepare OK
[Build] Addon pack OK
[Build] Finished in 0.35 s.

I used the xpi released in the repository. It worked

I'm not sure if I did something wrong. By the way, the Chinese document needs to be updated.

---

system information

windows 10 x64 - VMware Workstation
Node.js v18.16.0
Zotero 7.0.0-beta.9+5e41b3ab4 (64-bit)

Suggestion for developing new addons from templete

I imagine it's difficult to program. But here's a suggestion: you could re-edit this code to make the addons functional again in the recent version of Vertov (eg audio and video media files/https://web.archive.org/web/20130602162235/http://digitalhistory. concordia.ca/vertov/?page_id=6) and develop something to read texts by voice (https://github.com/ImperialSquid/zotero-zotts).

Update README-zhCN

@KikkiZ when you have time, thanks

[Feature Request] Submit a comment to issues/prs when new version released if them included in this release

This is only a example issue

---

#92 should close this issue, and a comment like this 👇 will comment to this issue after next version released:

🚀 This issue has been resolved in v1.1.1. See Release v1.1.1 for release notes.

What's the rule of the xhtml?

What's the rule of the xhtml file, like preferences.xhtml? I've looked up the MDN and it seems to be non standard xml, and I didn't find it in the repo's document or anywhere else.

[Announcement] Auto Hot Reload

Hi there,

I’m happy to tell you that the plugin hot reload (update code and resources without restarting Zotero) feature is done. I have added the Auto Hot Reload feature to the plugin template and invite you to take a look and have a try.

1. Run npm run start-watch. (If Zotero is already running, use npm run watch)
2. Coding. (Yes, that's all)

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

How to create a development environment without affecting normal use?

Hi @windingwind,

Thanks for the great template!

I am developing a plugin which works in Zotero 6 and 7. However, when I test the plugin, the settings and database of normal Zotero will be affected accordingly.

How can I create a dev env so that I can use another Zotero normally. Like:

1. Zotero 7 Normal: I will manage my own literature for paper writing.
2. Zotero 7 Dev: A separate database, settings and profile.
3. Zotero 6 Dev: A separate database, settings and profile.

Thanks!

Status of preference window?

Is the preference window currently working? Here, when selecting the add-on preferences, the last view will stay active.

How to make existing plugin compatible with Zotero 7 using this template?

I'm maintaining a small plugin used internally at our library, and I'll still need to make it compatible with Zotero 7. I thought using this template would be the easiest, and, given the multiple convenience feature it provides, also the most pleasant way. But, how would you actually do that? Clone the template into a new branch (how?), copy the relevant features, and, once Zotero 7 has been released, build a release from there? Any hints how that would be done most easily?

Need Examples of VirtualizedTable on Dialog 【需要对话框中插入表格的示例】

Background: I'm new to JavaScript/TypeScript and zotero plugin development is my first attempt to use JavaScript/TypeScript. Also, I'm not familiar with Zotero's API.

There's not yet an example that creates a VirtualizedTable in a Dialog according to the fragment brlow:

// src/modules/examples.ts
@example
static vtableExample() {
  ztoolkit.getGlobal("alert")("See src/modules/preferenceScript.ts");
}

I tried to creates a VirtualizedTable in a Dialog like below:

const renderLock = ztoolkit.getGlobal("Zotero").Promise.defer();
const dialogHelper = new ztoolkit.Dialog(10, 2);
dialogHelper.open("Dialog Example");
const tableHelper = new ztoolkit.VirtualizedTable(dialogHelper.window)

but it doesn't work. I don't know how to fix it.

For beginners, the vtableExample is rather necessary.

RightClickMenuItem vs RightClickMenuPopup

For some reason, the right click popup menu only appears if the right click menu item is also registered. Why is that? How would you only add a right click popup menu without a right click menu item?

Also, for some reason the right click popup menu disappears if I change

document.querySelector(
        "#zotero-itemmenu-addontemplate-test",
      ) as XUL.MenuItem,

to

document.querySelector(
        "#zotero-itemmenu-whatever",
      ) as XUL.MenuItem,

What am I missing here?

vTable for data entry?

Can I use the vtable container for manipulating settings? (E.g., I have a bunch of related settings, and I don't want to add an input box for each, but rather have them show up together in a table? Is that possible?

Compatibility with Zot6 and Zot7

Is this template currently compatible with both Zotero 6 and 7? If yes, do you have to do anything special for this?

meaning of @example?

What's the exact meaning and purpose of @example in the template? (A guess: it's probably somehow possible to keep the examples for reference, but suppress them when building. Is that correct? If so, how would that work?)

我按照教程进行开发环境的设置，在vscode中按F5，zotero也能重新启动，但是插件栏里面看不到插件，是配置有问题吗？

我的zotero bate 7安装在D盘下，profile调整到了zotero的安装目录（通过./zotero -p调整，方便管理和调试），zotero-cmd.json设置如下：

{
  "usage": "Copy and rename this file to zotero-cmd.json. Edit the cmd.",
  "killZoteroWindows": "taskkill /f /im zotero.exe",
  "killZoteroUnix": "kill -9 $(ps -x | grep zotero)",
  "startZotero": "D:\\MyCloud\\SoftCloud\\zoteroDEV\\zotero.exe --debugger --purgecaches", 
  "exec": {
    "@comment-zoteroBinPath": "Please input the path of the Zotero binary file in `zoteroBinPath`.",
    "@comment-zoteroBinPath-tip": "The path delimiter should be escaped as `\\` for win32. The path is `*/Zotero.app/Contents/MacOS/zotero` for MacOS.",
    "zoteroBinPath": "D:\\MyCloud\\SoftCloud\\zoteroDEV\\zotero.exe",

    "@comment-profilePath": "Please input the path of the profile used for development in `profilePath`.",
    "@comment-profilePath-tip": "Start the profile manager by `/path/to/zotero.exe -p` to create a profile for development",
    "@comment-profilePath-see": "https://www.zotero.org/support/kb/profile_directory",
    "profilePath": "D:\\MyCloud\\SoftCloud\\zoteroDEV\\myProfile",

    "@comment-dataDir": "Please input the directory where the database is located in dataDir",
    "@comment-dataDir-tip": "If this field is kept empty, Zotero will start with the default data.",
    "@comment-dataDir-see": "https://www.zotero.org/support/zotero_data",
    "dataDir": ""
  }
}

在profile文件夹下的extensions中也按照教程添加了以扩展id命名的文本文件，删除了prefs.js中包含extensions.lastAppBuildId 和extensions.lastAppVersion的行（每次按F5后这两行会自动添加回来）。

在编译后（F5）zotero也能自动启动，但是在addon中看不到任何插件，是哪个地方设置错误了吗？还是template有所更新？

[Announcement] Change to Localization System: dtd to ftl

Hi,

Zotero is getting rid of dtd files and introducing ftl (Fluent[1]). See what you should do in this PR: #48

All dtd and properties are replaced with ftl now. You may still use properties, but I don't want multiple locale systems, so they are replaced as well.

[1] https://firefox-source-docs.mozilla.org/l10n/fluent/tutorial.html#