From 72acc1b2feb798b158fbe56af79c40a203c1927e Mon Sep 17 00:00:00 2001 From: windingwind <33902321+windingwind@users.noreply.github.com> Date: Wed, 11 Jan 2023 15:50:51 +0800 Subject: [PATCH] Update README.md --- README.md | 172 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 108 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index bcc7d0c..de101ec 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ Search `@example` in `src/examples.ts`. The examples are called in `src/hooks.ts ### UI Examples -![image](https://user-images.githubusercontent.com/33902321/209274492-7aa94912-af38-4154-af46-dc8f59640de3.png) +![image](https://user-images.githubusercontent.com/33902321/211739774-cc5c2df8-5fd9-42f0-9cdf-0f2e5946d427.png) - registerStyleSheet(the official make-it-red example) - registerRightClickMenuItem @@ -71,11 +71,33 @@ Search `@example` in `src/examples.ts`. The examples are called in `src/hooks.ts - registerCustomCellRenderer - registerLibraryTabPanel - registerReaderTabPanel -- unregisterUIExamples + +### Preference Pane Examples + +![image](https://user-images.githubusercontent.com/33902321/211737987-cd7c5c87-9177-4159-b975-dc67690d0490.png) + +- Preferences bindings +- UI Events +- Tabel +- Locale + +See [`src/modules/preferenceScript.ts`](./src/modules/preferenceScript.ts) ## Quick Start Guide -- Fork this repo; +### Install Pre-built `xpi` + +See how the examples work by directly downloading the `xpi` file from GitHub release and install it to your Zotero. + +This is also how your plugin will be released and used by others. + +> The release do not promise any real functions. It is probably not up-to-date. +> +> The `xpi` package is a zip file. However, please don't modify it directly. Modify the source code and build it. + +### Build from Source + +- Fork this repo/Click `Use this template`; - Git clone the forked repo; - Enter the repo folder; - Modify the settings in `./package.json`, including: @@ -104,6 +126,65 @@ Search `@example` in `src/examples.ts`. The examples are called in `src/hooks.ts > - 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. +### Release + +To build and release, use +```shell +# 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 +``` + +### 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) + +2. Install Firefox 60(for Zotero 6)/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. + +```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 60(Zotero 6)/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 + +> Press `shift+F8` in FF 60, or 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". + +9. Connect to Zotero in Firefox. + +> In FF 60, click the hamburger menu in the top right -> web developer -> Connect..., then enter `localhost:6100`. + +> In FF 102, enter `localhost:6100` in the bottom input of remote-debugging page and click `add`. + +10. Click `connect` in the leftside-bar of Firefox remote-debugging page. + +11. Click "Inspect Main Process" + +### Debug in Zotero + +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 + +## Details + ### About Hooks > See also [`src/hooks.ts`](https://github.com/windingwind/zotero-plugin-template/blob/bootstrap/src/hooks.ts) @@ -170,6 +251,30 @@ The plugin template provides new APIs for bootstrap plugins. We have two reasons 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. +### About Build + +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`). + +Steps in `scripts/build.js`: + +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` + +### About Zotero API + +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. + ### Directory Structure This section shows the directory structure of a template. @@ -233,67 +338,6 @@ This section shows the directory structure of a template. └─ progressWindow.ts # progressWindow tool ``` -### Build - -```shell -# 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` - -### Build Steps - -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` - -### Debug - -1. Copy zotero command line config file. Modify the commands. - -```sh -cp ./scripts/zotero-cmd-default.json ./scripts/zotero-cmd.json -vim ./scripts/zotero-cmd.json -``` - -2. Setup plugin development environment following this [link](https://www.zotero.org/support/dev/client_coding/plugin_development#setting_up_a_plugin_development_environment). - -3. Build plugin and restart Zotero with this npm command. - -4. Launch Firefox 60 -5. 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`). -6. In Zotero, go to setting, advanced, config editor, look up "debugging" and click on "allow remote debugging" -7. In Firefox, click the hamburger menu in the top right -> web developer -> Connect... -8. Enter localhost:6100 -9. Connect -10. Click "Inspect Main Process" - -```sh -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](https://udn.realityripple.com/docs/Archive/Mozilla/XUL_Explorer). - > XUL Documents: - > https://www.xul.fr/tutorial/ - > http://www.xulplanet.com/ - -### Development - -**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](https://github.com/windingwind/zotero-types) provides most frequently used Zotero APIs. It's included in this template by default. - ## Disclaimer Use this code under AGPL. No warranties are provided. Keep the laws of your locality in mind!