Data Unbound

I’m currently learning how to program Zotero, specifically how to integrate Zotero with other applications. I document my learning experience to make it easier for others to learn what I’ve learned. Note that I’m still learning (I’m far from an expert) — so I think my advice will improve over time. But it decided not to wait until I am an expert before I share my experiences.

You can write Zotero plugins (a Firefox extension that accesses the Zotero extension) as a way of extending Zotero — see plugins [Zotero Documentation].

In a series of posts, I would like to explore how to use Chickenfoot as a scripting framework for Zotero and as a way to explore a working Zotero instance. Why Chickenfoot? Chickenfoot is appealing because it’s the closest thing we have to a Web automation framework running within a web browser — and hence something that can take advantage of all the scriptability and context of the Web browser. (Besides, much of the work we do with Chickenfoot will be transferable to writing a Zotero plug-in.)

A goal I’ve set for myself to focus my learning — and to provide a narrative for the series: create a Chickenfoot script to grab all the references I added on a given date and format those items to be sent out as HTML, wiki formatting, and to be uplaoded to some social bookmarking systems, including delicious and Connotea.

Note: I’m using v 1.0.7 of Zotero, running on Firefox 2.0.0.17 on Windows XP. I’m also using Chickenfoot v 1.0.4. I assume that you will have some basic knowledge of JavaScript and Firefox extensions. (I plan to provide more background later.) The overall approach we take here is a combination of experimenting with bits and pieces of source code, combined with reading the original Zotero source code.

In this first post, we warm up by studying how to access with Chickenfoot Zotero and ZoteroPane, two important Zotero objects, and perform some basic tasks with them.

First, the Zotero object is arguably the main JavaScript object, one that gives you access to the underlying functionality of Zotero. You can access it in this way (see include.js):

var Zotero = Components.classes["@zotero.org/Zotero;1"].
getService(Components.interfaces.nsISupports).wrappedJSObject;

or, in the context of Chickenfoot script:

var Zotero = chromeWindow.Zotero;

(See Rewrite the Web with Chickenfoot [JavaScript & Ajax Tutorials] for a description of the chromeWindow, which is the top-level object of the Firefox browser.)

From a thread on the Zotero forums, I learned an incantation (courtesy of Dan Stillman) to access the ZoteroPane:

var wm = Components.classes["@mozilla.org/appshell/window-mediator;1"]
.getService(Components.interfaces.nsIWindowMediator);
var browserWindow = wm.getMostRecentWindow("navigator:browser");
var ZoteroPane = browserWindow.ZoteroPane;


It turns out but you can also use chromeWindow to get at ZoteroPane:

var ZoteroPane = chromeWindow.ZoteroPane;

What can we do with Zotero and ZoteroPane?

The first thing to do is to examine the two objects. You can examine them the output panel by toggling the output variable to see the children of the output object. For example, if you run the following code, you can get a list of all the children of Zotero and ZoteroPane:


function list_props(obj) {
var name, props;
var props;
props = "";
for (name in obj) {
props = props + " " + name;
}
return props;
}
var Zotero = chromeWindow.Zotero;
var ZoteroPane = chromeWindow.ZoteroPane;
list_props(Zotero);


to generate the following list:


init stateCheck getProfileDirectory getZoteroDirectory getStorageDirectory getZoteroDatabase chooseZoteroDirectory debug log getErrors getSystemInfo varDump safeDebug getString localeJoin getLocaleCollation setFontSize flattenArguments getAncestorByTagName join inArray arraySearch arrayToHash hasValues randomString getRandomID moveToUnique initialized skipLoading startupError startupErrorHandler Prefs Keys Hash Text Date Browser UnresponsiveScriptIndicator WebProgressFinishListener JSON DBConnection DB Schema Item Items Notes Collection Collections Creators Tags CachedTypes CreatorTypes ItemTypes FileTypes CharacterSets ItemFields getCollections Attachments Notifier History Search Searches SearchConditions Ingester OpenURL Translate Cite CSL QuickCopy Report Timeline Utilities Integration File Fulltext MIME ItemTreeView ItemTreeCommandController CollectionTreeView CollectionTreeCommandController ItemGroup ProgressWindowSet ProgressWindow Annotate Annotations Annotation Highlight version isFx2 isFx3 platform isMac isWin isLinux locale dir Maps IconFactory


Calculating the number of top level items

The following simple Chickenfoot script returns the number of top-level items in my Zotero collection:


var Zotero = chromeWindow.Zotero;
var items = Zotero.Items.getAll(true);
items.length + 1;


Toggle the Zotero Panel

The following two-liner shows how to turn the Zotero display on and off (equivalent to hitting Ctrl-Alt-Z)