Zotero Connectors

Building

1. git clone --recursive https://github.com/zotero/zotero-connectors.git
2. cd zotero-connectors
3. npm install
4. ./build.sh -d

The connectors are built in build/.

Running from the build directory

Chrome

1. Go to chrome://extensions/
2. Enable "Developer Mode".
3. Click "Load unpacked extension…" and select the build/browserExt directory.

Firefox

1. Go to about:debugging
2. Click "Load Temporary Add-on" and select the build/browserExt/manifest.json file.

Safari

See https://github.com/zotero/safari-app-extension

Automatic rebuilding

1. cd to project root
2. npm install
3. build.sh -d
4. gulp watch

As files are changed, the connectors will be rebuilt automatically. You will need to manually reload the extension in the browser being developed for.

Requirements for packaging extensions from the command line

• Copy config.sh-sample to config.sh and modify as necessary

Developing

An overview of the Zotero Connector architecture.

Technologies

Chrome/Firefox Browser Extension Framework

The extension uses the WebExtension API cross-browser technology. See Chrome Extension docs and Firefox Extension docs for more information.

Safari Extension Framework

For Safari specifics see https://github.com/zotero/safari-app-extension

Zotero Translator Framework

The Connectors use the Zotero translate architecture, to support page translation. A basic understanding of how translation works is highly useful in understanding the codebase.

Components

Saving resources to Zotero library is facilitated by two major components: the Zotero Connector running in the browser and either the Zotero client or zotero.org web api. The Zotero Connector itself is split into two components: code running on the webpage and a background process.

a) Injected scripts for individual webpages

Each webpage is injected (Chrome/Firefox/Safari) with a full Zotero translation framework. A Zotero.Translate.Web instance orchestrates running individual translators for detection and translation.

The translation framework provides custom classes concerning translator retrieval and item saving. These custom classes talk to the background process (b) of the Zotero Connector for functionality outside the translation framework, such as retrieving translator code and sending translated items either to Zotero (c) or zotero.org (d).

b) Background process

The Connector runs a background process (Chrome/Firefox/Safari) which works as a middle-layer between the translation framework running in inject scripts (a) and Zotero (c) or zotero.org (d).

The background process maintains a cache of translators and performs the initial translator detection using URL matching. Translators whose target regexp matches the URL of a given webpage are then further tested by running detectWeb() in injected scripts. A list of translators and their code is fetched either from Zotero (c) or zotero.org (d).

The background process is also responsible for updating the extension UI, kicking off translations, storing and retrieving connector preferences and sending translated items to Zotero or zotero.org. Browser specific scripts are available for BrowserExt and Safari.

c) Connector server in Zotero

When Zotero is open it runs a connector HTTP server on port 23119. The HTTP server API accommodates interactions between the Connectors and Zotero client. Calls to Zotero.Connector.callMethod(endpoint) in this codebase are translated to HTTP requests to the connector server.

Note that Zotero cannot interact with the connectors on its own accord. All communication is Connector initiated.

d) zotero.org API

When Zotero is not available item saving falls back to using zotero.org API. The interactions with zotero.org API are defined in api.js

Message passing

The only way for the background extension process and injected scripts to communicate is using the message passing protocol provided by the browsers (Chrome/Firefox/Safari). Injected scripts often need to communicate to background scripts. To simplify these interactions, calls to functions in background scripts are monkey-patched in injected scripts. These calls are asynchronous and if a return value is required, it is provided either to a callback function as the last argument of the call or as a resolving value of a promise returned.

messages.js contains the list of the monkey-patched methods. If the method value is false no response is expected, otherwise the calls provide a response. An optional pre-send processing on the background end and post-receive processing on the injected end is possible to treat values that cannot be sent as-is via the messaging protocol.

The background process registers message listeners in messaging.js. Zotero.Messaging class also provides a way to send messages to injected scripts and add custom message listeners.

The injected scripts monkey-patch methods in messaging_injected.js(BrowserExt/Safari) Zotero.Messaging class also provides a way to send messages to the background process and add message listeners.

Contact

If you have any questions about developing Zotero Connectors you can join the discussion in the zotero-dev mailing list.