Update README.md
This commit is contained in:
windingwind
GitHub
parent
574ce88b9f
commit
d7210d930a
172
README.md
172
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**
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user