Class: UITool

UI APIs. Create elements and manage them.

Extends

BasicTool

Extended by

DialogHelper

Constructors

Constructor

new UITool(base?): UITool;

Defined in: src/tools/ui.ts:28

Parameters

base?

BasicTool | BasicOptions

Returns

UITool

Overrides

BasicTool.constructor

Properties

_basicOptions

protected _basicOptions: UIOptions;

Defined in: src/tools/ui.ts:11

UITool options

Overrides

BasicTool._basicOptions

_console?

protected optional _console: Console;

Defined in: src/basic.ts:16

Inherited from

BasicTool._console

elementCache

protected elementCache: WeakRef<Element>[];

Defined in: src/tools/ui.ts:26

Store elements created with this instance

Remarks

What is this for?

In bootstrap plugins, elements must be manually maintained and removed on exiting.

This API does this for you.

patchSign

protected readonly patchSign: string = "zotero-plugin-toolkit@3.0.0";

Defined in: src/basic.ts:21

Deprecated

Use patcherManager instead.

Inherited from

BasicTool.patchSign

_version

static _version: string = version;

Defined in: src/basic.ts:23

Inherited from

BasicTool._version

Accessors

_version

Get Signature

get _version(): string;

Defined in: src/basic.ts:28

Get version - checks subclass first, then falls back to parent

Returns

string

Inherited from

ZoteroToolkit._version

basicOptions

Get Signature

get basicOptions(): UIOptions;

Defined in: src/tools/ui.ts:13

Returns

UIOptions

Overrides

BasicTool.basicOptions

Methods

_ensureMainWindowListener()

protected _ensureMainWindowListener(): void;

Defined in: src/basic.ts:368

Ensure the main window listener is registered.

Returns

void

Inherited from

BasicTool._ensureMainWindowListener

_ensurePluginListener()

protected _ensurePluginListener(): void;

Defined in: src/basic.ts:418

Ensure the plugin listener is registered.

Returns

void

Inherited from

BasicTool._ensurePluginListener

_ensureRemoveListener()

protected _ensureRemoveListener(): void;

Defined in: src/basic.ts:349

Remove all Zotero event listener callbacks when the last callback is removed.

Returns

void

Inherited from

BasicTool._ensureRemoveListener

addListenerCallback()

addListenerCallback<T>(type, callback): void;

Defined in: src/basic.ts:319

Add a Zotero event listener callback

Type Parameters

T

T extends keyof ListenerCallbackMap

Parameters

type

T

Event type

callback

ListenerCallbackMap[T]

Event callback

Returns

void

Inherited from

BasicTool.addListenerCallback

appendElement()

appendElement(properties, container): Node;

Defined in: src/tools/ui.ts:322

Append element(s) to a node.

Parameters

properties

TagElementProps

See ElementProps

container

Element

The parent node to append to.

Returns

Node

A Node that is the appended child (aChild), except when aChild is a DocumentFragment, in which case the empty DocumentFragment is returned.

createElement()

Call Signature

createElement(
   doc,
   tagName,
   props?): DocumentFragment;

Defined in: src/tools/ui.ts:78

Create DocumentFragment.

Parameters

doc

Document

tagName

"fragment"

props?

FragmentElementProps

Returns

DocumentFragment

Example

const frag: DocumentFragment = ui.createElement(document, "fragment", {
  children: [{ tag: "h1", properties: { innerText: "Hello World!" } }],
});

Call Signature

createElement<HTML_TAG, T>(
   doc,
   tagName,
   props?): T;

Defined in: src/tools/ui.ts:113

Create HTMLElement.

Type Parameters

HTML_TAG

HTML_TAG extends keyof HTMLElementTagNameMap

T

Parameters

doc

Document

tagName

HTML_TAG

props?

HTMLElementProps

See ElementProps

Returns

T

Examples

const div: HTMLDivElement = ui.createElement(document, "div");

Attributes(for elem.setAttribute()), properties(for elem.prop=), listeners, and children.

const div: HTMLDivElement = ui.createElement(document, "div", {
  id: "hi-div",
  skipIfExists: true,
  listeners: [{ type: "click", listener: (e) => ui.log("Clicked!") }],
  children: [
    { tag: "h1", properties: { innerText: "Hello World!" } },
    { tag: "a", attributes: { href: "https://www.zotero.org" } },
  ],
});

Call Signature

createElement<XUL_TAG, T>(
   doc,
   tagName,
   props?): T;

Defined in: src/tools/ui.ts:128

Create XULElement.

Type Parameters

XUL_TAG

XUL_TAG extends keyof XULElementTagNameMap

T

Parameters

doc

Document

tagName

XUL_TAG

props?

XULElementProps

See ElementProps

Returns

T

See

ElementProps

Example

const menuitem: XULMenuItem = ui.createElement(document, "menuitem", {
  attributes: { label: "Click Me!" },
});

Call Signature

createElement<SVG_TAG, T>(
   doc,
   tagName,
   props?): T;

Defined in: src/tools/ui.ts:138

Create SVGElement

Type Parameters

SVG_TAG

SVG_TAG extends keyof SVGElementTagNameMap

T

Parameters

doc

Document

tagName

SVG_TAG

props?

SVGElementProps

See ElementProps

Returns

T

Call Signature

createElement(
   doc,
   tagName,
   props?): HTMLElement | SVGElement | XULElement;

Defined in: src/tools/ui.ts:148

Create Element

Parameters

doc

Document

tagName

string

props?

ElementProps

See ElementProps

Returns

HTMLElement | SVGElement | XULElement

Call Signature

createElement(
   doc,
   tagName,
   namespace?,
   enableElementRecord?): DocumentFragment | HTMLElement | SVGElement | XULElement;

Defined in: src/tools/ui.ts:160

Parameters

doc

Document

target document, e.g. Zotero main window.document

tagName

string

element tag name, e.g. hbox, div

namespace?

default "html"

"html" | "svg" | "xul"

enableElementRecord?

boolean

If current element will be recorded and maintained by toolkit. If not set, use this.enableElementRecordGlobal

Returns

DocumentFragment | HTMLElement | SVGElement | XULElement

Deprecated

createXULElement()

createXULElement(doc, type): XULElement;

Defined in: src/basic.ts:212

Create an XUL element

For Zotero 6, use createElementNS;

For Zotero 7+, use createXULElement.

Parameters

doc

Document

type

string

Returns

XULElement

Example

Create a <menuitem>:

const compat = new ZoteroCompat();
const doc = compat.getWindow().document;
const elem = compat.createXULElement(doc, "menuitem");

Inherited from

BasicTool.createXULElement

getGlobal()

Call Signature

getGlobal(k): typeof Zotero;

Defined in: src/basic.ts:93

Alpha

Parameters

k

"Zotero" | "zotero"

Returns

typeof Zotero

Inherited from

BasicTool.getGlobal

Call Signature

getGlobal(k): ZoteroPane;

Defined in: src/basic.ts:98

Alpha

Parameters

k

"ZoteroPane" | "ZoteroPane_Local"

Returns

ZoteroPane

Inherited from

BasicTool.getGlobal

Call Signature

getGlobal(k): Zotero_Tabs;

Defined in: src/basic.ts:103

Alpha

Parameters

k

"Zotero_Tabs"

Returns

Zotero_Tabs

Inherited from

BasicTool.getGlobal

Call Signature

getGlobal(k): any;

Defined in: src/basic.ts:108

Alpha

Parameters

k

"Zotero_File_Interface"

Returns

any

Inherited from

BasicTool.getGlobal

Call Signature

getGlobal(k): any;

Defined in: src/basic.ts:113

Alpha

Parameters

k

"Zotero_File_Exporter"

Returns

any

Inherited from

BasicTool.getGlobal

Call Signature

getGlobal(k): any;

Defined in: src/basic.ts:118

Alpha

Parameters

k

"Zotero_LocateMenu"

Returns

any

Inherited from

BasicTool.getGlobal

Call Signature

getGlobal(k): any;

Defined in: src/basic.ts:123

Alpha

Parameters

k

"Zotero_Report_Interface"

Returns

any

Inherited from

BasicTool.getGlobal

Call Signature

getGlobal(k): any;

Defined in: src/basic.ts:128

Alpha

Parameters

k

"Zotero_Timeline_Interface"

Returns

any

Inherited from

BasicTool.getGlobal

Call Signature

getGlobal(k): any;

Defined in: src/basic.ts:133

Alpha

Parameters

k

"Zotero_Tooltip"

Returns

any

Inherited from

BasicTool.getGlobal

Call Signature

getGlobal(k): ZoteroContextPane;

Defined in: src/basic.ts:138

Alpha

Parameters

k

"ZoteroContextPane"

Returns

ZoteroContextPane

Inherited from

BasicTool.getGlobal

Call Signature

getGlobal(k): any;

Defined in: src/basic.ts:143

Alpha

Parameters

k

"ZoteroItemPane"

Returns

any

Inherited from

BasicTool.getGlobal

Call Signature

getGlobal<K, GLOBAL>(k): GLOBAL[K];

Defined in: src/basic.ts:148

Alpha

Type Parameters

K

GLOBAL

GLOBAL extends typeof globalThis

Parameters

k

K

Returns

GLOBAL[K]

Inherited from

BasicTool.getGlobal

Call Signature

getGlobal(k): any;

Defined in: src/basic.ts:156

Get global variables.

Parameters

k

string

Global variable name, Zotero, ZoteroPane, window, document, etc.

Returns

any

Inherited from

BasicTool.getGlobal

insertElementBefore()

insertElementBefore(properties, referenceNode): undefined | Node;

Defined in: src/tools/ui.ts:334

Inserts a node before a reference node as a child of its parent node.

Parameters

properties

TagElementProps

See ElementProps

referenceNode

Element

The node before which newNode is inserted.

Returns

undefined | Node

Node

isXULElement()

isXULElement(elem): boolean;

Defined in: src/basic.ts:189

If it's an XUL element

Parameters

elem

Element

Returns

boolean

Inherited from

BasicTool.isXULElement

log()

log(...data): void;

Defined in: src/basic.ts:221

Output to both Zotero.debug and console.log

Parameters

data

...any

e.g. string, number, object, ...

Returns

void

Inherited from

BasicTool.log

parseXHTMLToFragment()

parseXHTMLToFragment(
   str,
   entities,
   defaultXUL): DocumentFragment;

Defined in: src/tools/ui.ts:380

Parse XHTML to XUL fragment. For Zotero 6.

To load preferences from a Zotero 7's .xhtml, use this method to parse it.

Parameters

str

string

xhtml raw text

entities

string[] = []

dtd file list ("chrome://xxx.dtd")

defaultXUL

boolean = true

true for default XUL namespace

Returns

DocumentFragment

patch()

patch<T, K>(
   object,
   funcSign,
   ownerSign,
   patcher): void;

Defined in: src/basic.ts:300

Patch a function

Type Parameters

T

T

K

K extends string | number | symbol

Parameters

object

T

The owner of the function

funcSign

K

The signature of the function(function name)

ownerSign

string

The signature of patch owner to avoid patching again

patcher

(fn) => T[K]

The new wrapper of the patched function

Returns

void

Deprecated

Use PatchHelper instead.

Inherited from

BasicTool.patch

removeListenerCallback()

removeListenerCallback<T>(type, callback): void;

Defined in: src/basic.ts:337

Remove a Zotero event listener callback

Type Parameters

T

T extends keyof ListenerCallbackMap

Parameters

type

T

Event type

callback

ListenerCallbackMap[T]

Event callback

Returns

void

Inherited from

BasicTool.removeListenerCallback

replaceElement()

replaceElement(properties, oldNode): undefined | Node;

Defined in: src/tools/ui.ts:358

Replace oldNode with a new one.

Parameters

properties

ElementProps & object

See ElementProps

oldNode

Element

The child to be replaced.

Returns

undefined | Node

The replaced Node. This is the same node as oldChild.

unregisterAll()

unregisterAll(): void;

Defined in: src/tools/ui.ts:50

Remove all elements created by createElement.

Returns

void

Remarks

What is this for?

In bootstrap plugins, elements must be manually maintained and removed on exiting.

This API does this for you.

updateOptions()

updateOptions(source?): UITool;

Defined in: src/basic.ts:442

Parameters

source?

BasicTool | BasicOptions

Returns

UITool

Inherited from

BasicTool.updateOptions

getZotero()

static getZotero(): typeof Zotero;

Defined in: src/basic.ts:454

Returns

typeof Zotero

Inherited from

BasicTool.getZotero

wait

Variables

Functions

Class: UITool ​

Extends ​

Extended by ​

Constructors ​

Constructor ​

Parameters ​

base? ​

Returns ​

Overrides ​

Properties ​

_basicOptions ​

Overrides ​

_console? ​

Inherited from ​

elementCache ​

Remarks ​

patchSign ​

Deprecated ​

Inherited from ​

_version ​

Inherited from ​

Accessors ​

_version ​

Get Signature ​

Returns ​

Inherited from ​

basicOptions ​

Get Signature ​

Returns ​

Overrides ​

Methods ​

_ensureMainWindowListener() ​

Returns ​

Inherited from ​

_ensurePluginListener() ​

Returns ​

Inherited from ​

_ensureRemoveListener() ​

Returns ​

Inherited from ​

addListenerCallback() ​

Type Parameters ​

T ​

Parameters ​

type ​

callback ​

Returns ​

Inherited from ​

appendElement() ​

Parameters ​

properties ​

container ​

Returns ​

createElement() ​

Call Signature ​

Parameters ​

doc ​

tagName ​

props? ​

Returns ​

Example ​

Call Signature ​

Type Parameters ​

HTML_TAG ​

T ​

Parameters ​

doc ​

tagName ​

props? ​

Returns ​

Examples ​

Call Signature ​

Type Parameters ​

XUL_TAG ​

T ​

Parameters ​

doc ​

Class: UITool

Extends

Extended by

Constructors

Constructor

Parameters

base?

Returns

Overrides

Properties

_basicOptions

Overrides

_console?

Inherited from

elementCache

Remarks

patchSign

Deprecated

Inherited from

_version

Inherited from

Accessors

_version

Get Signature

Returns

Inherited from

basicOptions

Get Signature

Returns

Overrides

Methods

_ensureMainWindowListener()

Returns

Inherited from

_ensurePluginListener()

Returns

Inherited from

_ensureRemoveListener()

Returns

Inherited from

addListenerCallback()

Type Parameters

T

Parameters

type

callback

Returns

Inherited from

appendElement()

Parameters

properties

container

Returns

createElement()

Call Signature

Parameters

doc

tagName

props?

Returns

Example

Call Signature

Type Parameters

HTML_TAG

T

Parameters

doc

tagName

props?

Returns

Examples

Call Signature

Type Parameters

XUL_TAG

T

Parameters

doc

tagName

props?

Returns