Cita: a Wikidata addon for Zotero

A Zotero plugin adding citation metadata support, with back and forth communication to WikiData, citation extraction from file attachments, and local citation network visualization.

Initial development of this plugin was supported by a grant from the Wikimedia Foundation.

Description

The plugin consists of four separate basic modules:

Citation metadata support

This module adds citation metadata support to Zotero. It provides an additional Citations tab where the user can:

add, edit or remove individual citations;
run item-wide and citation specific actions, such as syncing citations with WikiData, parsing citations from attachments (not yet supported), etc;
edit source item's UUIDs, such as DOI, WikiData's QID, and OpenCitations Corpus ID.

Citations metadata are currently saved as a note attachment.

WikiData communication

This module provides back and forth citation syncing with WikiData, using property P2860 "cites work".

Local Citation Network visualization

This module allows visualizing how items in a local library connect to each other through citations, using Tim Wölfle's Local Citation Network.

Citation extraction (to be developed)

This module will send file attachments to local or remote citation extraction services (e.g., Grobid, Scholarcy) and retrieve parsed citations from them.

Installation

Download the latest XPI and install it in Zotero.

Quickstart guide

Quickstart guide available at Wikidata's Cita page.

Translation

Cita is collaboratively translated at translatewiki.net. Would you like to help translate it to other languages? Join the translation project here!

Development

Clone the source code, and run git submodule update --init --recursive to fetch the nested submodules.
Run npm install
This plugin is built using Webpack and Babel. Run npm run build, or npm run watch to rebuild automatically each time the source code is changed. Built files will be saved to dist/chrome/content.
Follow the steps here to have Zotero run the plugin directly from the dist directory.
Start Zotero with these recommended flags:
- -p <Profile>: runs Zotero with a custom development profile to avoid breaking your personal library
- -purgecaches: forces Zotero to re-read any cached files
- -ZoteroDebugText: prints the debug output to the terminal window
- -jsconsole: opens a basic JavaScript debug console; this is not necessary if you be debugging using your browser (see below), but it may help you detect early errors without having to open the developer tools
For distribution, pack the contents of the dist directory into a ZIP file and change its extension to .xpi.

Publishing

Decide new version number vX.Y.Z using Semantic Versioning.
Update version number in:
- /package.json
- /static/install.rdf
Update version and updateLinks in /update.rdf.
Run git clean -xdf to remove untracked files, including /dist and /node_modules.
Run npm install. This will also update /package-lock.json with the new version.
Zip the contents of /dist into a zip file named zotero-cita-vX.Y.Z.xpi. E. g. cd dist && zip -r ../zotero-cita-v0.0.1.xpi *
Until integration tests have been implemented (#30), install the new version on a fresh Zotero profile and run some manual tests.
Run git commit -m "Bump vX.Y.Z" and git push.
Run git tag vX.Y.Z and git push --tags.
On GitHub, create a new release:
1. Choose tag vX.Y.Z.
2. Set release title "vX.Y.Z".
3. In the description, list changes since last release.
4. Attach the xpi file created above.
5. Click "Publish release" and hope everything is alright.

Debugging

To debug, you need to build Zotero with debugging support. Follow the instructions here to:

Clone Zotero source code and scripts.
Build the Zotero client. See [1] below
Build the Zotero standalone client with the -t option.
Run Zotero with the -debugger flag: staging/Zotero_linux-x86_64/zotero -debugger .... This runs the Mozilla DevTools server on port 6100, which you can connect to from Firefox Developer Tools.
Download and use a Firefox version compatible with the Firefox version used by Zotero. For example, Zotero 5.0.94 is based on Firefox 60.9.0esr. See [2] below
Run the Firefox version you downloaded using the --new-instance flag in case you have another Firefox instance running, and the -p <Profile> flag to use a separate profile for this version.
Open Firefox Developer Tools and connect to port 6100 for remote debugging. See [3] below

[1] Before building, making these changes to the Zotero source code might help you with debugging:

If your browser developer tools are failing to retrieve the source maps for the compiled Zotero files, try using inline source maps instead. To do this, add a sourceMaps: "inline" key:value pair to the .babelrc configuration file.
Zotero has a notification system such that observers can be registered to be notified when certain events occur, such as when an item is modified. However, this notification system is not thoroughly documented. To log a message to the Zotero debug output each time a notification is triggered, uncomment the two calls to Zotero.debug() that you will find in the Zotero.Notifier.trigger function inside chrome/content/zotero/xpcom/notifier.js. Make sure you are running Zotero with the -ZoteroDebugText flag (see previous section).

[2] To prevent your downloaded Firefox version from upgrading to a newer version, you have to disable automatic updates:

Run your system's Firefox version from the command line with the -P flag to open the Profile Manager.
Create a new profile that you will use with the Firefox version you downloaded.
Click on 'Start Firefox' to start your system Firefox using the profile you have just created.
Go to about:config and set app.udpate.auto to false.
Close your system Firefox.
Run the Firefox version you downloaded using the -P <ProfileName> flag.

The reason why the setting must be changed using your system Firefox is because it seems that Firefox checks for updates on startup, before one can change the setting. And if an update is found, it will be applied on next start, irrespective of this setting's value, overwriting the version you downloaded.

[3] Unfortunately the developer tools are closed automatically when the Zotero client is closed. Therefore, each time a change is made to the plugin, the Zotero client must be restarted, and the developer tools have to be opened again. If someone knows of a way to prevent developer tools from closing and reconnect when connection is available again, or to have them open automatically via console, so it can be run immediately after Zotero, please let me know!

Acknowledgements

Cita depends on:

maxlath's wikibase-edit & wikibase-sdk
Philipp Zumstein's QuickStatements translator for Zotero
Tim Wölfle's Local Citation Network
React

Support for importing/exporting citations from/to a file, among other contributions, were mostly implemented by Dominic DallOsto.

License

This work is released under the terms of GPL-3.0 or any later version.

It has been suggested that new Zotero plugins be written as bootstrapped extensions rather than XUL overlay extensions, to facilitate them being ported to a future non-Mozilla version of Zotero. As suggested elsewhere, Will Shanks' Zutilo plugin was used as an example of an existing bootstrapped extension to write some parts of this plugin.

Doing anything new in XUL has also been strongly recommended against, and using standard React/HTML has been suggested instead (see here, or here). For these cases, some inspiration has been borrowed from already reactified components in Zotero's source code.

dpriskorn / zotero-cita