From 9c824d6faa6cbc90814792aa84e857e2b153ed9b Mon Sep 17 00:00:00 2001 From: Northword Date: Sat, 1 Jul 2023 17:54:55 +0800 Subject: [PATCH 1/3] Update readme --- README.md | 197 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 104 insertions(+), 93 deletions(-) diff --git a/README.md b/README.md index 7ef0f7f..e4dde80 100644 --- a/README.md +++ b/README.md @@ -7,22 +7,23 @@ This is a plugin template for [Zotero](https://www.zotero.org/). Plugins created with this template: -![GitHub Repo stars](https://img.shields.io/github/stars/windingwind/zotero-better-notes?label=zotero-better-notes&style=flat-square) -![GitHub Repo stars](https://img.shields.io/github/stars/windingwind/zotero-pdf-preview?label=zotero-pdf-preview&style=flat-square) -![GitHub Repo stars](https://img.shields.io/github/stars/windingwind/zotero-pdf-translate?label=zotero-pdf-translate&style=flat-square) -![GitHub Repo stars](https://img.shields.io/github/stars/windingwind/zotero-tag?label=zotero-tag&style=flat-square) -![GitHub Repo stars](https://img.shields.io/github/stars/iShareStuff/ZoteroTheme?label=zotero-theme&style=flat-square) -![GitHub Repo stars](https://img.shields.io/github/stars/MuiseDestiny/zotero-reference?label=zotero-reference&style=flat-square) -![GitHub Repo stars](https://img.shields.io/github/stars/MuiseDestiny/zotero-citation?label=zotero-citation&style=flat-square) -![GitHub Repo stars](https://img.shields.io/github/stars/MuiseDestiny/ZoteroStyle?label=zotero-style&style=flat-square) -![GitHub Repo stars](https://img.shields.io/github/stars/volatile-static/Chartero?label=Chartero&style=flat-square) -![GitHub Repo stars](https://img.shields.io/github/stars/l0o0/tara?label=tara&style=flat-square) -![GitHub Repo stars](https://img.shields.io/github/stars/redleafnew/delitemwithatt?label=delitemwithatt&style=flat-square) -![GitHub Repo stars](https://img.shields.io/github/stars/redleafnew/zotero-updateifsE?label=zotero-updateifsE&style=flat-square) -![GitHub Repo stars](https://img.shields.io/github/stars/inciteful-xyz/inciteful-zotero-plugin?label=inciteful-zotero-plugin&style=flat-square) -![GitHub Repo stars](https://img.shields.io/github/stars/MuiseDestiny/zotero-gpt?label=zotero-gpt&style=flat-square) -![GitHub Repo stars](https://img.shields.io/github/stars/zoushucai/zotero-journalabbr?label=zotero-journalabbr&style=flat-square) -![GitHub Repo stars](https://img.shields.io/github/stars/MuiseDestiny/zotero-figure?label=zotero-figure&style=flat-square) +[![GitHub Repo stars](https://img.shields.io/github/stars/windingwind/zotero-better-notes?label=zotero-better-notes&style=flat-square)](https://github.com/windingwind/zotero-better-notes) +[![GitHub Repo stars](https://img.shields.io/github/stars/windingwind/zotero-pdf-preview?label=zotero-pdf-preview&style=flat-square)](https://github.com/windingwind/zotero-pdf-preview) +[![GitHub Repo stars](https://img.shields.io/github/stars/windingwind/zotero-pdf-translate?label=zotero-pdf-translate&style=flat-square)](https://github.com/windingwind/zotero-pdf-translate) +[![GitHub Repo stars](https://img.shields.io/github/stars/windingwind/zotero-tag?label=zotero-tag&style=flat-square)](https://github.com/windingwind/zotero-tag) +[![GitHub Repo stars](https://img.shields.io/github/stars/iShareStuff/ZoteroTheme?label=zotero-theme&style=flat-square)](https://github.com/iShareStuff/ZoteroTheme) +[![GitHub Repo stars](https://img.shields.io/github/stars/MuiseDestiny/zotero-reference?label=zotero-reference&style=flat-square)](https://github.com/MuiseDestiny/zotero-reference) +[![GitHub Repo stars](https://img.shields.io/github/stars/MuiseDestiny/zotero-citation?label=zotero-citation&style=flat-square)](https://github.com/MuiseDestiny/zotero-citation) +[![GitHub Repo stars](https://img.shields.io/github/stars/MuiseDestiny/ZoteroStyle?label=zotero-style&style=flat-square)](https://github.com/MuiseDestiny/ZoteroStyle) +[![GitHub Repo stars](https://img.shields.io/github/stars/volatile-static/Chartero?label=Chartero&style=flat-square)](https://github.com/volatile-static/Chartero) +[![GitHub Repo stars](https://img.shields.io/github/stars/l0o0/tara?label=tara&style=flat-square)](https://github.com/l0o0/tara) +[![GitHub Repo stars](https://img.shields.io/github/stars/redleafnew/delitemwithatt?label=delitemwithatt&style=flat-square)](https://github.com/redleafnew/delitemwithatt) +[![GitHub Repo stars](https://img.shields.io/github/stars/redleafnew/zotero-updateifsE?label=zotero-updateifsE&style=flat-square)](https://github.com/redleafnew/zotero-updateifsE) +[![GitHub Repo stars](https://img.shields.io/github/stars/northword/zotero-format-metadata?label=zotero-format-metadata&style=flat-square)](https://github.com/northword/zotero-format-metadata) +[![GitHub Repo stars](https://img.shields.io/github/stars/inciteful-xyz/inciteful-zotero-plugin?label=inciteful-zotero-plugin&style=flat-square)](https://github.com/inciteful-xyz/inciteful-zotero-plugin) +[![GitHub Repo stars](https://img.shields.io/github/stars/MuiseDestiny/zotero-gpt?label=zotero-gpt&style=flat-square)](https://github.com/MuiseDestiny/zotero-gpt) +[![GitHub Repo stars](https://img.shields.io/github/stars/zoushucai/zotero-journalabbr?label=zotero-journalabbr&style=flat-square)](https://github.com/zoushucai/zotero-journalabbr) +[![GitHub Repo stars](https://img.shields.io/github/stars/MuiseDestiny/zotero-figure?label=zotero-figure&style=flat-square)](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) @@ -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. -> 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,19 +182,19 @@ 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: (Zotero 7 beta: ) 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). @@ -203,7 +204,7 @@ vim ./scripts/zotero-cmd.json 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: ## Details @@ -298,7 +299,7 @@ Steps in `scripts/build.js`: ### 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 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. @@ -319,56 +320,66 @@ This section shows the directory structure of a template. > Don't break the lines in the `defaults.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 +|-- builds/ # 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 From ac15ec50355e8946ee91341d96f75fcb5888ee46 Mon Sep 17 00:00:00 2001 From: Northword Date: Sat, 1 Jul 2023 18:23:44 +0800 Subject: [PATCH 2/3] Update readme due to typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e4dde80..0949b1a 100644 --- a/README.md +++ b/README.md @@ -352,7 +352,7 @@ This section shows the directory structure of a template. | | `-- preferences.ftl | |-- manifest.json # addon config | `-- prefs.js -|-- builds/ # build dir +|-- build/ # build dir |-- scripts # scripts for dev | |-- build.mjs # esbuild and replace | |-- reload.mjs From 5cf4e57228889ee4ab7fa18cd41814d7110c8f12 Mon Sep 17 00:00:00 2001 From: Northword Date: Sat, 1 Jul 2023 22:04:10 +0800 Subject: [PATCH 3/3] Fix typo in readme --- README.md | 55 +++++++++++++++++++++++++++---------------------------- 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 0949b1a..6083f1e 100644 --- a/README.md +++ b/README.md @@ -25,15 +25,15 @@ Plugins created with this template: [![GitHub Repo stars](https://img.shields.io/github/stars/zoushucai/zotero-journalabbr?label=zotero-journalabbr&style=flat-square)](https://github.com/zoushucai/zotero-journalabbr) [![GitHub Repo stars](https://img.shields.io/github/stars/MuiseDestiny/zotero-figure?label=zotero-figure&style=flat-square)](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. @@ -162,7 +162,7 @@ This is also how your plugin will be released and used by others. > 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? > @@ -184,27 +184,27 @@ npm run release 1. Install a beta version of Zotero: (Zotero 7 beta: ) -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". @@ -287,15 +287,15 @@ 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 @@ -305,19 +305,18 @@ Zotero docs are outdated and incomplete. Clone 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 .