windingwind
GitHub
commit
55368dea50
238
README.md
238
README.md
@ -7,32 +7,33 @@ This is a plugin template for [Zotero](https://www.zotero.org/).
|
|||||||
|
|
||||||
Plugins created with this template:
|
Plugins created with this template:
|
||||||
|
|
||||||
|
[](https://github.com/windingwind/zotero-better-notes)
|
||||||
|
[](https://github.com/windingwind/zotero-pdf-preview)
|
||||||
|
[](https://github.com/windingwind/zotero-pdf-translate)
|
||||||
|
[](https://github.com/windingwind/zotero-tag)
|
||||||
|
[](https://github.com/iShareStuff/ZoteroTheme)
|
||||||
|
[](https://github.com/MuiseDestiny/zotero-reference)
|
||||||
|
[](https://github.com/MuiseDestiny/zotero-citation)
|
||||||
|
[](https://github.com/MuiseDestiny/ZoteroStyle)
|
||||||
|
[](https://github.com/volatile-static/Chartero)
|
||||||
|
[](https://github.com/l0o0/tara)
|
||||||
|
[](https://github.com/redleafnew/delitemwithatt)
|
||||||
|
[](https://github.com/redleafnew/zotero-updateifsE)
|
||||||
|
[](https://github.com/northword/zotero-format-metadata)
|
||||||
|
[](https://github.com/inciteful-xyz/inciteful-zotero-plugin)
|
||||||
|
[](https://github.com/MuiseDestiny/zotero-gpt)
|
||||||
|
[](https://github.com/zoushucai/zotero-journalabbr)
|
||||||
|
[](https://github.com/MuiseDestiny/zotero-figure)
|
||||||
|
|
||||||
📖[Plugin Development Documentation](https://zotero.yuque.com/books/share/8d230829-6004-4934-b4c6-685a7001bfa0/vec88d)(Chinese, provides English translation)
|
📖 [Plugin Development Documentation](https://zotero.yuque.com/books/share/8d230829-6004-4934-b4c6-685a7001bfa0/vec88d) (Chinese, provides English translation)
|
||||||
|
|
||||||
🛠️[Zotero Plugin Toolkit](https://github.com/windingwind/zotero-plugin-toolkit) | [API Documentation](https://github.com/windingwind/zotero-plugin-toolkit/blob/master/docs/zotero-plugin-toolkit.md)
|
🛠️ [Zotero Plugin Toolkit](https://github.com/windingwind/zotero-plugin-toolkit) | [API Documentation](https://github.com/windingwind/zotero-plugin-toolkit/blob/master/docs/zotero-plugin-toolkit.md)
|
||||||
|
|
||||||
ℹ️[Zotero Type Definitions](https://github.com/windingwind/zotero-types)
|
ℹ️ [Zotero Type Definitions](https://github.com/windingwind/zotero-types)
|
||||||
|
|
||||||
📜[Zotero Source Code](https://github.com/zotero/zotero)
|
📜 [Zotero Source Code](https://github.com/zotero/zotero)
|
||||||
|
|
||||||
📌[Zotero Plugin Template](https://github.com/windingwind/zotero-plugin-template)(This repo)
|
📌 [Zotero Plugin Template](https://github.com/windingwind/zotero-plugin-template) (This repo)
|
||||||
|
|
||||||
> 👁 Watch this repo so that you can be notified whenever there are fixes & updates.
|
> 👁 Watch this repo so that you can be notified whenever there are fixes & updates.
|
||||||
|
|
||||||
@ -141,32 +142,32 @@ This is also how your plugin will be released and used by others.
|
|||||||
- Enter the repo folder;
|
- Enter the repo folder;
|
||||||
- Modify the settings in `./package.json`, including:
|
- Modify the settings in `./package.json`, including:
|
||||||
|
|
||||||
```json5
|
```json5
|
||||||
{
|
{
|
||||||
version,
|
version,
|
||||||
author,
|
author,
|
||||||
description,
|
description,
|
||||||
homepage,
|
homepage,
|
||||||
config {
|
config {
|
||||||
releasepage, // URL to releases(`.xpi`)
|
releasepage, // URL to releases(`.xpi`)
|
||||||
updaterdf, // URL to update.json
|
updaterdf, // URL to update.json
|
||||||
addonName, // name to be displayed in the plugin manager
|
addonName, // name to be displayed in the plugin manager
|
||||||
addonID, // ID to avoid confliction. IMPORTANT!
|
addonID, // ID to avoid confliction. IMPORTANT!
|
||||||
addonRef, // e.g. Element ID prefix
|
addonRef, // e.g. Element ID prefix
|
||||||
addonInstance // the plugin's root instance: Zotero.${addonInstance}
|
addonInstance // the plugin's root instance: Zotero.${addonInstance}
|
||||||
|
}
|
||||||
}
|
}
|
||||||
}
|
```
|
||||||
```
|
|
||||||
|
|
||||||
> Be careful to set the addonID and addonRef to avoid confliction.
|
> 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](https://nodejs.org/en/);
|
- Run `npm install` to set up the plugin and install dependencies. If you don't have NodeJS installed, please download it [here](https://nodejs.org/en/);
|
||||||
- Run `npm run build` to build the plugin in production mode. Run `npm run build-dev` to build the plugin in development mode. The xpi for installation and the built code is under `builds` folder.
|
- Run `npm run build` to build the plugin in production mode. Run `npm run build-dev` to build the plugin in development mode. The xpi for installation and the built code is under `build` folder.
|
||||||
|
|
||||||
> What the difference between dev & prod?
|
> What the difference between dev & prod?
|
||||||
>
|
>
|
||||||
> - This environment variable is stored in `Zotero.${addonInstance}.data.env`. The outputs to console is disabled in prod mode.
|
> - 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.
|
> - You can decide what users cannot see/use based on this variable.
|
||||||
|
|
||||||
### Release
|
### Release
|
||||||
|
|
||||||
@ -181,29 +182,29 @@ npm run release
|
|||||||
|
|
||||||
### Setup Development Environment
|
### Setup Development Environment
|
||||||
|
|
||||||
1. Install a beta version of Zotero: https://www.zotero.org/support/beta_builds (Zotero 7 beta: https://www.zotero.org/support/dev/zotero_7_for_developers)
|
1. Install a beta version of Zotero: <https://www.zotero.org/support/beta_builds> (Zotero 7 beta: <https://www.zotero.org/support/dev/zotero_7_for_developers>)
|
||||||
|
|
||||||
2. Install Firefox 102(for Zotero 7)
|
2. Install Firefox 102 (for Zotero 7)
|
||||||
|
|
||||||
3. Copy zotero command line config file. Modify the commands that starts your installation of the beta Zotero.
|
3. Copy zotero command line config file. Modify the commands that starts your installation of the beta Zotero.
|
||||||
|
|
||||||
> (Optional) Do this only once: Start the beta Zotero with `/path/to/zotero -p`. Create a new profile and use it as your development profile.
|
> (Optional) Do this only once: Start the beta Zotero with `/path/to/zotero -p`. Create a new profile and use it as your development profile.
|
||||||
> Use `/path/to/zotero -p {profile_name}` to specify which profile to run with.
|
> Use `/path/to/zotero -p {profile_name}` to specify which profile to run with.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
cp ./scripts/zotero-cmd-default.json ./scripts/zotero-cmd.json
|
cp ./scripts/zotero-cmd-default.json ./scripts/zotero-cmd.json
|
||||||
vim ./scripts/zotero-cmd.json
|
vim ./scripts/zotero-cmd.json
|
||||||
```
|
```
|
||||||
|
|
||||||
4. Setup plugin development environment following this [link](https://www.zotero.org/support/dev/client_coding/plugin_development#setting_up_a_plugin_development_environment).
|
4. Setup plugin development environment following this [link](https://www.zotero.org/support/dev/client_coding/plugin_development#setting_up_a_plugin_development_environment).
|
||||||
|
|
||||||
5. Build plugin and restart Zotero with `npm run restart`.
|
5. Build plugin and restart Zotero with `npm run restart`.
|
||||||
|
|
||||||
6. Launch Firefox 102(Zotero 7)
|
6. Launch Firefox 102 (Zotero 7)
|
||||||
|
|
||||||
7. In Firefox, go to devtools, go to settings, click "enable remote debugging" and the one next to it that's also about debugging
|
7. In Firefox, go to devtools, go to settings, click "enable remote debugging" and the one next to it that's also about debugging
|
||||||
|
|
||||||
> Enter `about:debugging#/setup` in FF 102.
|
> Enter `about:debugging#/setup` in FF 102.
|
||||||
|
|
||||||
8. In Zotero, go to setting, advanced, config editor, look up "debugging" and click on "allow remote debugging".
|
8. In Zotero, go to setting, advanced, config editor, look up "debugging" and click on "allow remote debugging".
|
||||||
|
|
||||||
@ -239,7 +240,7 @@ You can also:
|
|||||||
- Test code snipastes in Tools->Developer->Run Javascript;
|
- Test code snipastes in Tools->Developer->Run Javascript;
|
||||||
- Debug output with `Zotero.debug()`. Find the outputs in Help->Debug Output Logging->View Output;
|
- 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](https://udn.realityripple.com/docs/Archive/Mozilla/XUL_Explorer).
|
- Debug UI. Zotero is built on the Firefox XUL framework. Debug XUL UI with software like [XUL Explorer](https://udn.realityripple.com/docs/Archive/Mozilla/XUL_Explorer).
|
||||||
> XUL Documentation: http://www.devdoc.net/web/developer.mozilla.org/en-US/docs/XUL.html
|
> XUL Documentation: <http://www.devdoc.net/web/developer.mozilla.org/en-US/docs/XUL.html>
|
||||||
|
|
||||||
## Details
|
## Details
|
||||||
|
|
||||||
@ -286,89 +287,98 @@ createElement(document, "button", { namespace: "xul" }); // manually set namespa
|
|||||||
|
|
||||||
Use Esbuild to build `.ts` source code to `.js`.
|
Use Esbuild to build `.ts` source code to `.js`.
|
||||||
|
|
||||||
Use `replace-in-file` to replace keywords and configurations defined in `package.json` in non-build files (`.xul/xhtml`, `.dtd`, and `.properties`).
|
Use `replace-in-file` to replace keywords and configurations defined in `package.json` in non-build files (`xhtml`, `.flt`, et. al.).
|
||||||
|
|
||||||
Steps in `scripts/build.js`:
|
Steps in `scripts/build.mjs`:
|
||||||
|
|
||||||
1. Clean `./builds`
|
1. Clean `./build`
|
||||||
2. Copy `./addon` to `./builds`
|
2. Copy `./addon` to `./build`
|
||||||
3. Esbuild to `./builds/addon/chrome/content/scripts`
|
3. Esbuild to `./build/addon/chrome/content/scripts`
|
||||||
4. Replace `__buildVersion__` and `__buildTime__` in `./builds/addon`
|
4. Replace `__buildVersion__` and `__buildTime__` in `./build/addon`
|
||||||
5. Zip the `./builds/addon` to `./builds/*.xpi`
|
5. Zip the `./build/addon` to `./build/*.xpi`
|
||||||
|
|
||||||
### About Zotero API
|
### About Zotero API
|
||||||
|
|
||||||
Zotero docs are outdated and incomplete. Clone https://github.com/zotero/zotero and search the keyword globally.
|
Zotero docs are outdated and incomplete. Clone <https://github.com/zotero/zotero> and search the keyword globally.
|
||||||
|
|
||||||
> ⭐The [zotero-types](https://github.com/windingwind/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.
|
> ⭐The [zotero-types](https://github.com/windingwind/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:
|
A trick for finding the API you want:
|
||||||
|
|
||||||
Search the UI label in `.xul`(`.xhtml`)/`.dtd`/`.properties` files, find the corresponding key in locale file. Then search this keys in `.js`/`.jsx` files.
|
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
|
### Directory Structure
|
||||||
|
|
||||||
This section shows the directory structure of a template.
|
This section shows the directory structure of a template.
|
||||||
|
|
||||||
- All `.js/.ts` code files are in `./src`;
|
- All `.js/.ts` code files are in `./src`;
|
||||||
- Addon config files: `./addon/chrome.manifest`, `./addon/install.rdf`, and `./addon/manifest.json`;
|
- Addon config files: `./addon/manifest.json`;
|
||||||
- UI files: `./addon/chrome/content/*.xhtml`.
|
- UI files: `./addon/chrome/content/*.xhtml`.
|
||||||
- Locale files: `./addon/chrome/locale/[*.dtd, *.properties]`;
|
- Locale files: `./addon/locale/**/*.flt`;
|
||||||
- Resource files: `./addon/chrome/skin/default/__addonRef__/*.dtd`;
|
- Preferences file: `./addon/prefs.js`;
|
||||||
- Preferences file: `./addon/chrome/defaults/preferences/defaults.js`;
|
> Don't break the lines in the `prefs.js`
|
||||||
> Don't break the lines in the `defaults.js`
|
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
│ .gitignore
|
.
|
||||||
│ .release-it.json # release-it conf
|
|-- .eslintrc.json # eslint conf
|
||||||
| tsconfig.json # https://code.visualstudio.com/docs/languages/jsconfig#
|
|-- .gitattributes # git conf
|
||||||
│ build.js # esbuild
|
|-- .github/ # github conf
|
||||||
│ LICENSE
|
|-- .gitignore # git conf
|
||||||
│ package.json # npm conf
|
|-- .prettierrc # prettier conf
|
||||||
│ README.md # readme
|
|-- .release-it.json # release-it conf
|
||||||
│ update.rdf # addon update
|
|-- .vscode # vs code conf
|
||||||
│
|
| |-- extensions.json
|
||||||
├─.github # github conf
|
| |-- launch.json
|
||||||
│
|
| |-- setting.json
|
||||||
├─addon # addon dir
|
| `-- toolkit.code-snippets
|
||||||
│ │ manifest.json # addon config
|
|-- package-lock.json # npm conf
|
||||||
│ │ bootstrap.js # addon load/unload script, like a main.c
|
|-- package.json # npm conf
|
||||||
│ │
|
|-- LICENSE
|
||||||
│ └─chrome
|
|-- README.md
|
||||||
│ ├─content # UI
|
|-- addon
|
||||||
│ │ │ preferences.xhtml
|
| |-- bootstrap.js # addon load/unload script, like a main.c
|
||||||
│ │ │
|
| |-- chrome
|
||||||
│ │ ├─icons
|
| | `-- content
|
||||||
│ │ │ favicon.png
|
| | |-- icons/
|
||||||
│ │ │ favicon@0.5x.png
|
| | |-- preferences.xhtml # preference panel
|
||||||
│ │ │
|
| | `-- zoteroPane.css
|
||||||
│ │ └─scripts
|
| |-- locale # locale
|
||||||
│ └─locale # locale
|
| | |-- en-US
|
||||||
│ ├─en-US
|
| | | |-- addon.ftl
|
||||||
│ │ overlay.dtd
|
| | | `-- preferences.ftl
|
||||||
│ │ addon.properties
|
| | `-- zh-CN
|
||||||
│ │
|
| | |-- addon.ftl
|
||||||
│ ├─zh-CN
|
| | `-- preferences.ftl
|
||||||
│ | overlay.dtd
|
| |-- manifest.json # addon config
|
||||||
│ └─ addon.properties
|
| `-- prefs.js
|
||||||
│
|
|-- build/ # build dir
|
||||||
├─builds # build dir
|
|-- scripts # scripts for dev
|
||||||
│ └─.xpi
|
| |-- build.mjs # esbuild and replace
|
||||||
│
|
| |-- reload.mjs
|
||||||
└─src # source code
|
| |-- start.mjs
|
||||||
│ index.ts # main entry
|
| |-- stop.mjs
|
||||||
│ addon.ts # base class
|
| `-- zotero-cmd-default.json
|
||||||
│ hooks.ts # lifecycle hooks
|
|-- src # source code
|
||||||
|
|
| |-- addon.ts # base class
|
||||||
└─modules # sub modules
|
| |-- hooks.ts # lifecycle hooks
|
||||||
│ examples.ts # examples factory
|
| |-- index.ts # main entry
|
||||||
│ locale.ts # locale .properties
|
| |-- modules # sub modules
|
||||||
│ preferenceScript.ts # script runs in preferences.xhtml
|
| | |-- examples.ts
|
||||||
└─ progressWindow.ts # progressWindow tool
|
| | `-- 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-template.json # template of `update.json`
|
||||||
|
`-- update.json
|
||||||
```
|
```
|
||||||
|
|
||||||
## Disclaimer
|
## Disclaimer
|
||||||
|
|
||||||
Use this code under AGPL. No warranties are provided. Keep the laws of your locality in mind!
|
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
|
If you want to change the license, please contact me at <wyzlshx@foxmail.com>
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user