Update README.md
This commit is contained in:
windingwind
GitHub
parent
574ce88b9f
commit
d7210d930a
168
README.md
168
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));
|
- Release to GitHub automatically(using [release-it](https://github.com/release-it/release-it));
|
||||||
- Extensive skeleton;
|
- Extensive skeleton;
|
||||||
- Some sample code of UI and lifecycle.
|
- Some sample code of UI and lifecycle.
|
||||||
|
- ⭐Compatibilities for Zotero 6 & Zotero 7.
|
||||||
|
|
||||||
## Quick Start Guide
|
## 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 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.
|
- 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**
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
https://github.com/windingwind/zotero-addon-template/blob/574ce88b9fd3535a9d062db51cf16e99dda35288/src/views.ts#L52-L60
|
||||||
|
|
||||||
|
**Item Menu**
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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<MenuitemOptions>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 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.
|
||||||
|
|
||||||
|
<table style="margin-left: auto; margin-right: auto;">
|
||||||
|
<tr>
|
||||||
|
<td>
|
||||||
|
<img height="400" src="https://user-images.githubusercontent.com/33902321/208080125-2a776a98-f427-4c81-8924-7877bf803e3d.png"/>
|
||||||
|
<div>Zotero 7</div>
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
<img height="400" src="https://user-images.githubusercontent.com/33902321/208080491-b7006c08-2679-4f85-9a28-dba8e622d745.png"/>
|
||||||
|
<div>Zotero 6</div>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
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<ElementOptions>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
### Directory Structure
|
### Directory Structure
|
||||||
|
|
||||||
This section shows the directory structure of a template.
|
This section shows the directory structure of a template.
|
||||||
@ -71,21 +218,19 @@ This section shows the directory structure of a template.
|
|||||||
│ │
|
│ │
|
||||||
│ └─chrome
|
│ └─chrome
|
||||||
│ ├─content # UI
|
│ ├─content # UI
|
||||||
│ │ │ preferences.xul
|
│ │ │ preferences.xhtml
|
||||||
|
│ │ │
|
||||||
|
│ │ ├─icons
|
||||||
|
│ │ │ favicon.png
|
||||||
|
│ │ │ favicon@0.5x.png
|
||||||
│ │ │
|
│ │ │
|
||||||
│ │ └─scripts
|
│ │ └─scripts
|
||||||
│ ├─locale # locale
|
│ └─locale # locale
|
||||||
│ │ ├─en-US
|
│ ├─en-US
|
||||||
│ │ │ overlay.dtd
|
|
||||||
│ │ │
|
|
||||||
│ │ └─zh-CN
|
|
||||||
│ │ overlay.dtd
|
│ │ overlay.dtd
|
||||||
│ │
|
│ │
|
||||||
│ └─skin # style
|
│ └─zh-CN
|
||||||
│ └─default
|
│ overlay.dtd
|
||||||
│ └─addonname
|
|
||||||
│ favicon.png
|
|
||||||
│ favicon@0.5x.png
|
|
||||||
│
|
│
|
||||||
├─builds # build dir
|
├─builds # build dir
|
||||||
│ └─.xpi
|
│ └─.xpi
|
||||||
@ -95,6 +240,7 @@ This section shows the directory structure of a template.
|
|||||||
│ module.ts # module class
|
│ module.ts # module class
|
||||||
│ addon.ts # base class
|
│ addon.ts # base class
|
||||||
│ events.ts # events class
|
│ events.ts # events class
|
||||||
|
│ utils.ts # Utils class
|
||||||
│ views.ts # UI class
|
│ views.ts # UI class
|
||||||
└─ prefs.ts # preferences class
|
└─ prefs.ts # preferences class
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user