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:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[](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.
|
||||
|
||||
@ -141,32 +142,32 @@ This is also how your plugin will be released and used by others.
|
||||
- Enter the repo folder;
|
||||
- Modify the settings in `./package.json`, including:
|
||||
|
||||
```json5
|
||||
{
|
||||
version,
|
||||
author,
|
||||
description,
|
||||
homepage,
|
||||
config {
|
||||
releasepage, // URL to releases(`.xpi`)
|
||||
updaterdf, // URL to update.json
|
||||
addonName, // name to be displayed in the plugin manager
|
||||
addonID, // ID to avoid confliction. IMPORTANT!
|
||||
addonRef, // e.g. Element ID prefix
|
||||
addonInstance // the plugin's root instance: Zotero.${addonInstance}
|
||||
```json5
|
||||
{
|
||||
version,
|
||||
author,
|
||||
description,
|
||||
homepage,
|
||||
config {
|
||||
releasepage, // URL to releases(`.xpi`)
|
||||
updaterdf, // URL to update.json
|
||||
addonName, // name to be displayed in the plugin manager
|
||||
addonID, // ID to avoid confliction. IMPORTANT!
|
||||
addonRef, // e.g. Element ID prefix
|
||||
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 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?
|
||||
>
|
||||
> - 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.
|
||||
> 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.
|
||||
> - You can decide what users cannot see/use based on this variable.
|
||||
|
||||
### Release
|
||||
|
||||
@ -181,29 +182,29 @@ npm run release
|
||||
|
||||
### 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.
|
||||
|
||||
> (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.
|
||||
> (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.
|
||||
|
||||
```sh
|
||||
cp ./scripts/zotero-cmd-default.json ./scripts/zotero-cmd.json
|
||||
vim ./scripts/zotero-cmd.json
|
||||
```
|
||||
```sh
|
||||
cp ./scripts/zotero-cmd-default.json ./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).
|
||||
|
||||
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
|
||||
|
||||
> 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".
|
||||
|
||||
@ -239,7 +240,7 @@ You can also:
|
||||
- Test code snipastes 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](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
|
||||
|
||||
@ -286,89 +287,98 @@ createElement(document, "button", { namespace: "xul" }); // manually set namespa
|
||||
|
||||
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`
|
||||
2. Copy `./addon` to `./builds`
|
||||
3. Esbuild to `./builds/addon/chrome/content/scripts`
|
||||
4. Replace `__buildVersion__` and `__buildTime__` in `./builds/addon`
|
||||
5. Zip the `./builds/addon` to `./builds/*.xpi`
|
||||
1. Clean `./build`
|
||||
2. Copy `./addon` to `./build`
|
||||
3. Esbuild to `./build/addon/chrome/content/scripts`
|
||||
4. Replace `__buildVersion__` and `__buildTime__` in `./build/addon`
|
||||
5. Zip the `./build/addon` to `./build/*.xpi`
|
||||
|
||||
### 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.
|
||||
|
||||
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
|
||||
|
||||
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`;
|
||||
- Addon config files: `./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`
|
||||
- Locale files: `./addon/locale/**/*.flt`;
|
||||
- Preferences file: `./addon/prefs.js`;
|
||||
> Don't break the lines in the `prefs.js`
|
||||
|
||||
```shell
|
||||
│ .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
|
||||
│ │ manifest.json # addon config
|
||||
│ │ 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
|
||||
.
|
||||
|-- .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 # esbuild and replace
|
||||
| |-- reload.mjs
|
||||
| |-- start.mjs
|
||||
| |-- stop.mjs
|
||||
| `-- zotero-cmd-default.json
|
||||
|-- 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-template.json # template of `update.json`
|
||||
`-- 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 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