Zotero API cookbook start

=head1 Zotero API documentation

=head2 Setting up a simplified development environment

The easiest way to set up a development environment for Zotero is to download
L<http://wiki.github.com/bard/mozrepl/|MozRepl>, an interactive shell available
by telnetting to localhost on port 4242 (by default).  Linux and Mac OS X users
can use the built in telnet client.  Windows users should use
L<http://www.chiark.greenend.org.uk/~sgtatham/putty/|Putty>.There's also a
firefox plugin to provide MozRepl access
L<http://ubik.cc/2009/09/mozrepl-in-a-panel.html|directly inside firefox>.

Setting up a firefox development environment is beyond the scope of this
document.

Perl programmers should be aware of the L<MozRepl> CPAN module, and the closely
related L<MozRepl::RemoteObject> which allows you to access Javascript objects
from inside perl programs.

B<NOTE> With a longer script I've had trouble with MozRepl timing out on me for
no apparent reason.  The solution to this is to either send the code to the
terminal application in smaller sized chunks, or to keep pasting the code in
until it works.  Unfortunately in some cases missing semicolons and curly
brackets can cause silent failure in the REPL as well which means that
debugging longer bits of code can be interesting.  Avoid this by avoiding
excessively long blocks of procedural code - factor everything into smaller
functions wherever possible.

=head3 Zotero API Howtos

The Zotero API is under-documented, and at present requires a lot of looking
around in the source code.  The most useful parts of the source code are in
chrome/content/zotero/xpcom and xpcom/data, and the chrome/content/zotero
(particularly overlay.js and fileInterface.js)

=head4 Create new Zotero object

This is the first thing that you need to do when interacting with zotero's
internals.  The code to do so is:

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

=head5 Setup a Zotero search

If you are focused on data access, then the first thing you will want to do
will be to retrieve items from your zotero.  Creating an in-memory search is a
good start.

    var search = new z.Search();

=head5  Search for items containing a specific tag

Starting with the code from "Setup a Zotero search" we then use the following
code to retreive items with a particular tag:

    search.addCondition('tag', 'is', 'tag name here');

=head5 Search for a Zotero subcollection

TODO

=head5 Select a Zotero saved search

TODO

=head5 Search term operators

TODO

=head5 Combining search terms

TODO

=head5 Complete list of search operators

TODO (should be pretty easy)

=head5 Complete list of search fields

TODO (with description of what the more obscure fields mean - e.g. extra for
abstract, and how do we search the fulltext archive?)

=head5 Executing the search

Once the search conditions have been set up, then it's time to execute the
results:

    var results = search.search();

This returns the item ids in the search as an array [I could be wrong ... ].
The next thing to do is to get the Zotero items for the array of IDs:

    var items = z.Items.get(results);

=head5 Getting a bibliography for an array of items:

Here we use zotero's quickcopy functions to get a bibliography in the style
specified in Zotero's preferences.

First we start with a list of as in the previous entry.

  var qc = z.QuickCopy;
  var biblio = qc.getContentFromItems(new Array(item),
                                      z.Prefs.get("export.quickCopy.setting"));
    var biblio_html_format = cite.html;
    var biblio_txt         = cite.txt;

TODO:  get citations.  change the style.  get stuff in other formats,
especially RTF

=head5 Get information about an item.

TODO:  need to list all the possible fields here, and what kind of entry they
belong to.

To get an item's abstract, we get the 'extra' field from the Zotero item:

    var abstract = item.getField('extra');

=head5 Get fulltext for an item.

TODO

=head5 Get stored attachements for an item

TODO

=head5 Get child notes for an item

To get the child notes for an item, we use the following code:

    var notes = item.getNotes();

This returns an array of notes.  Each note is in HTML format.  To get each note
in turn we just iterate through the array:

    for (var j=0;j<notes.length;j++) {
        var note = z.Items.get(notes[j]);
        var note_html = note.getNote;
    }

=head5 Get an item's related items

This technique works for anything that can have related items attached within
the zotero database.  This includes items and notes.

  var related_items = item.relatedItemsBidirectional

This returns a list of items just like in the search examples.

=head4  Generic XUL Javascript to provide support functions

=head5 Writing out a file:

This function will write out a file to a specified filename.  If the file
already exists it will be silently overwritten.  [TODO: obviously this needs to
be cleaned up, talk about append mode as well, and failure if file already
exists ...]

  function writeFile(filename, data)    {
      var file = Components.classes["@mozilla.org/file/local;1"].createInstance(Components.interfaces.nsILocalFile);
      var foStream = Components.classes["@mozilla.org/network/file-output-stream;1"].createInstance(Components.interfaces.nsIFileOutputStream);
      file.initWithPath(filename); 
      foStream.init(file, 0x02 , 00666, 0);
      foStream.write(data, data.length);
      foStream.close();
  };

  writeFile("/tmp/boo.txt", "boo\n");

=head5 TODO

many other things :)