From d7210d930ab8f8e5eca3d6602ed25b3863f6f805 Mon Sep 17 00:00:00 2001 From: windingwind <33902321+windingwind@users.noreply.github.com> Date: Fri, 16 Dec 2022 19:00:20 +0800 Subject: [PATCH] Update README.md --- README.md | 172 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 159 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 731fbef..4ce30de 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ This is an addon/plugin template for [Zotero](https://www.zotero.org/). - Release to GitHub automatically(using [release-it](https://github.com/release-it/release-it)); - Extensive skeleton; - Some sample code of UI and lifecycle. +- ⭐Compatibilities for Zotero 6 & Zotero 7. ## Quick Start Guide @@ -40,6 +41,152 @@ This is an addon/plugin template for [Zotero](https://www.zotero.org/). - Run `npm install` to setup 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. The xpi for installation and the built code is under builds folder. +### Examples + +#### Menu (file, edit, view, ...) & Right-click Menu (item, collection/library) + +**File Menu** + +![image](https://user-images.githubusercontent.com/33902321/208077117-e9ae3ca8-f9c7-4549-8835-1de5ea8c665f.png) + +https://github.com/windingwind/zotero-addon-template/blob/574ce88b9fd3535a9d062db51cf16e99dda35288/src/views.ts#L52-L60 + +**Item Menu** + +![image](https://user-images.githubusercontent.com/33902321/208078502-75d547b7-1cff-4538-802a-3d5127a8b617.png) + +https://github.com/windingwind/zotero-addon-template/blob/574ce88b9fd3535a9d062db51cf16e99dda35288/src/views.ts#L23-L51 + +`Utils.UI.insertMenuItem` resolved the input object and inject the menu items. + +Available types `menuFile`, `menuEdit`, ...: +```ts +defaultMenuPopupSelectors: { + menuFile: "#menu_FilePopup", + menuEdit: "#menu_EditPopup", + menuView: "#menu_viewPopup", + menuGo: "#menu_goPopup", + menuTools: "#menu_ToolsPopup", + menuHelp: "#menu_HelpPopup", + collection: "#zotero-collectionmenu", + item: "#zotero-itemmenu", +}, +``` + +You can choose an anchor element and insert before/after it using `insertPosition` and `anchorElement`. Default the insert position is the end of menu. + +```ts +insertMenuItem: ( + menuPopup: XUL.Menupopup | string, + options: MenuitemOptions, + insertPosition?: "before" | "after", + anchorElement?: XUL.Element +) => boolean; +``` + +Full options you can use: + +```ts +declare interface MenuitemOptions { + tag: "menuitem" | "menu" | "menuseparator"; + id?: string; + label?: string; + // data url (chrome://xxx.png) or base64 url (data:image/png;base64,xxx) + icon?: string; + class?: string; + styles?: { [key: string]: string }; + hidden?: boolean; + disabled?: boolean; + oncommand?: string; + commandListener?: EventListenerOrEventListenerObject; + // Attributes below are used when type === "menu" + popupId?: string; + onpopupshowing?: string; + subElementOptions?: Array; +} +``` + +#### Preference, for both Zotero 6 and Zotero 7 (all in bootstrap) + +Zotero 6 doesn't support preference pane injection in bootstrap mode, thus I write a register for Zotero 6 or lower. + +You only need to maintain one `preferences.xhtml` which runs natively on Zotero 7 and let the plugin template handle when it is running on Zotero 6. + + + + + + +
+ +
Zotero 7
+ 		+ +
Zotero 6
+
+ +https://github.com/windingwind/zotero-addon-template/blob/574ce88b9fd3535a9d062db51cf16e99dda35288/src/views.ts#L63-L82 + +Call `Utils.Compat.registerPrefPane` when it's on Zotero 6. Please make sure `defaultXUL` is set `true` as Zotero 6 requires that. + +Remember to call `Utils.Compat.unregisterPrefPane()` on plugin onload. + +https://github.com/windingwind/zotero-addon-template/blob/574ce88b9fd3535a9d062db51cf16e99dda35288/src/views.ts#L88-L90 + +#### 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 `Utils.UI.createElement`, the plugin template will maintain these elements. Just `Utils.UI.removeAddonElements` on exit. +- Zotero 7 requires createElement()/createElementNS() → createXULElement() for remaining XUL elements, while on Zotero 6 doesn't support `createXULElement`. Using `Utils.UI.createElement`, it switches API depending on the current platform automatically. + +Definition: + +```ts +function createElement ( + doc: Document, + tagName: string, + namespace: "html" | "svg" | "xul" +) => XUL.Element | DocumentFragment | HTMLElement | SVGAElement; +``` + +There are more advanced APIs for creating elements in batch: `Uitls.UI.creatElementsFromJSON`. Input a element tree in JSON and return a fragment/element. These elements are also maintained by plugin template. + +Definition: + +```ts +function creatElementsFromJSON ( + doc: Document, + options: ElementOptions +) => XUL.Element | DocumentFragment | HTMLElement | SVGAElement; +``` + +Available options: + +```ts +declare interface ElementOptions { + tag: string; + id?: string; + namespace?: "html" | "svg" | "xul"; + styles?: { [key: string]: string }; + directAttributes?: { [key: string]: string | boolean | number }; + attributes?: { [key: string]: string | boolean | number }; + listeners?: Array< + | [ + string, + EventListenerOrEventListenerObject, + boolean | AddEventListenerOptions + ] + | [string, EventListenerOrEventListenerObject] + >; + checkExistanceParent?: HTMLElement; + ignoreIfExists?: boolean; + removeIfExists?: boolean; + customCheck?: () => boolean; + subElementOptions?: Array; +} +``` + ### Directory Structure This section shows the directory structure of a template. @@ -71,21 +218,19 @@ This section shows the directory structure of a template. │ │ │ └─chrome │ ├─content # UI -│ │ │ preferences.xul +│ │ │ preferences.xhtml +│ │ │ +│ │ ├─icons +│ │ │ favicon.png +│ │ │ favicon@0.5x.png │ │ │ │ │ └─scripts -│ ├─locale # locale -│ │ ├─en-US -│ │ │ overlay.dtd -│ │ │ -│ │ └─zh-CN -│ │ overlay.dtd -│ │ -│ └─skin # style -│ └─default -│ └─addonname -│ favicon.png -│ favicon@0.5x.png +│ └─locale # locale +│ ├─en-US +│ │ overlay.dtd +│ │ +│ └─zh-CN +│ overlay.dtd │ ├─builds # build dir │ └─.xpi @@ -95,6 +240,7 @@ This section shows the directory structure of a template. │ module.ts # module class │ addon.ts # base class │ events.ts # events class + │ utils.ts # Utils class │ views.ts # UI class └─ prefs.ts # preferences class