Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revision | Last revisionBoth sides next revision | ||
dev:api_user_docs [2011/03/04 18:43] – dstillman | dev:api_user_docs [2011/04/16 15:59] – rmzelle | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== Zotero API documentation ====== | + | See [[dev/client_coding/JavaScript |
- | + | ||
- | This documentation is a work in progress, and at this stage you see many TODO entries in the list. There are also things I haven' | + | |
- | + | ||
- | ===== The simplest Zotero development environment ===== | + | |
- | + | ||
- | The two easiest way to set up a development environment for Zotero is with the Firefox extension | + | |
- | + | ||
- | An example of getting POW to interact with Zotero which creates a rich annotated bibliography from data stored inside zoters is available as a [[http:// | + | |
- | + | ||
- | ===== The second simplest development environment ====== | + | |
- | + | ||
- | There are a number of suitable interactive javascript environments for interacting with Firefox' | + | |
- | + | ||
- | - [[http:// | + | |
- | - [[http:// | + | |
- | - A Firefox plugin to provide MozRepl access [[http:// | + | |
- | - The [[https:// | + | |
- | + | ||
- | Setting up a Firefox development environment is beyond the scope of this | + | |
- | document. | + | |
- | + | ||
- | Perl programmers should be aware of the [[http:// | + | |
- | related [[http:// | + | |
- | from inside perl programs. | + | |
- | + | ||
- | **A problem with MozREPL**: With a longer script I've had trouble with MozRepl timing out on me for no apparent reason. | + | |
- | + | ||
- | ===== Zotero API Howtos ===== | + | |
- | + | ||
- | The Zotero API is under-documented, | + | |
- | + | ||
- | ==== Create new Zotero object ==== | + | |
- | + | ||
- | This is the first thing that you need to do when interacting with zotero' | + | |
- | internals. | + | |
- | + | ||
- | <code javascript> | + | |
- | var Zotero = Components.classes[" | + | |
- | </ | + | |
- | + | ||
- | ==== Get the Zotero Pane to interact with the Zotero GUI ==== | + | |
- | + | ||
- | <code javascript> | + | |
- | + | ||
- | var ZoteroPane = Components.classes[" | + | |
- | + | ||
- | </ | + | |
- | + | ||
- | Then grab the currently selected items from the zotero pane: | + | |
- | + | ||
- | <code javascript> | + | |
- | + | ||
- | //get first selected item | + | |
- | var selected_items = ZoteroPane.getSelectedItems(); | + | |
- | var item = selected_items[0]; | + | |
- | + | ||
- | // proced if selected item is neither a collection nor a note | + | |
- | if ( ! item.isCollection() & ! item.isNote()) { | + | |
- | if (item.isAttachment()) { | + | |
- | // find out about attachment | + | |
- | } | + | |
- | if (item.isRegularItem()) { | + | |
- | // we could grab attachments: | + | |
- | // var att_ids = item.getAttachments(false); | + | |
- | // if (att_ids.length> | + | |
- | // item_att=Zotero.Items.get(att_ids[0]); | + | |
- | } | + | |
- | alert(item.id); | + | |
- | } | + | |
- | + | ||
- | </ | + | |
- | + | ||
- | ==== 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. | + | |
- | good start. | + | |
- | + | ||
- | <code javascript> | + | |
- | + | ||
- | ==== Search for items containing a specific tag ==== | + | |
- | + | ||
- | Starting with the code from "Setup a Zotero search" | + | |
- | code to retrieve items with a particular tag: | + | |
- | + | ||
- | <code javascript> | + | |
- | + | ||
- | ==== Zotero Collection Operations ==== | + | |
- | + | ||
- | === Get the collection tree and display as a series of nested ordered lists === | + | |
- | + | ||
- | This code was developed in the firefox extension Plain Old Webserver server side javascript. | + | |
- | + | ||
- | <code javascript> | + | |
- | var Zotero = Components.classes[" | + | |
- | + | ||
- | var render_collection = function(coll) { | + | |
- | if (!coll) { | + | |
- | coll = null; | + | |
- | } | + | |
- | var collections = Zotero.getCollections(coll); | + | |
- | document.writeln("< | + | |
- | for (c in collections) { | + | |
- | document.writeln('< | + | |
- | if (collections[c].hasChildCollections) { | + | |
- | var childCol = render_collection(collections[c].id); | + | |
- | } | + | |
- | } | + | |
- | document.writeln("</ | + | |
- | } | + | |
- | + | ||
- | render_collection(); | + | |
- | </ | + | |
- | + | ||
- | === Get the items for a particular collection === | + | |
- | + | ||
- | <code javascript> | + | |
- | var Zotero = Components.classes[" | + | |
- | var collectionid = pow_server.GET.id; | + | |
- | var collection = z.Collections.get(collectionid); | + | |
- | var items = collection.getChildItems(); | + | |
- | // or you can obtain an array of itemIDs instead: | + | |
- | var itemids = collection.getChildItems(true); | + | |
- | </ | + | |
- | + | ||
- | ==== Select a Zotero saved search ==== | + | |
- | + | ||
- | TODO | + | |
- | + | ||
- | ==== Zotero Search Basics ==== | + | |
- | + | ||
- | + | ||
- | === Set up the search === | + | |
- | + | ||
- | <code javascript> | + | |
- | var s = new Zotero.Search(); | + | |
- | s.addCondition(' | + | |
- | // advanced search GUI | + | |
- | </ | + | |
- | + | ||
- | To add the other conditions available in the advanced search GUI, use the following: | + | |
- | + | ||
- | <code javascript> | + | |
- | s.addCondition(' | + | |
- | s.addCondition(' | + | |
- | s.addCondition(' | + | |
- | </ | + | |
- | + | ||
- | There are also some " | + | |
- | + | ||
- | One example is: | + | |
- | + | ||
- | <code javascript> | + | |
- | s.addCondition(' | + | |
- | </ | + | |
- | + | ||
- | === Search by collection === | + | |
- | + | ||
- | To search for a collection or a saved search you need to know the ID: | + | |
- | + | ||
- | <source javascript> | + | |
- | s.addCondition(' | + | |
- | s.addCondition(' | + | |
- | </ | + | |
- | + | ||
- | === Search by tag === | + | |
- | + | ||
- | To search by tag, you use the tag text: | + | |
- | + | ||
- | <source javascript> | + | |
- | var tagname = ' | + | |
- | search.addCondition(' | + | |
- | </ | + | |
- | + | ||
- | === Search by other fields === | + | |
- | + | ||
- | The complete list of other fields available to search on is on the [[./ | + | |
- | + | ||
- | ==== Combining search terms ==== | + | |
- | + | ||
- | TODO | + | |
- | + | ||
- | ==== Complete list of search operators ==== | + | |
- | + | ||
- | TODO (should be pretty easy) | + | |
- | + | ||
- | ==== Complete list of search fields ==== | + | |
- | + | ||
- | TODO (with description of what the more obscure fields mean - e.g. abstractNote for | + | |
- | abstract, and how do we search the fulltext archive?) | + | |
- | + | ||
- | ==== Executing the search ==== | + | |
- | + | ||
- | Once the search conditions have been set up, then it's time to execute the | + | |
- | results: | + | |
- | + | ||
- | <code javascript> | + | |
- | + | ||
- | 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: | + | |
- | + | ||
- | <code javascript> | + | |
- | + | ||
- | ==== Getting a bibliography for an array of items: ==== | + | |
- | + | ||
- | Here we use zotero' | + | |
- | specified in Zotero' | + | |
- | + | ||
- | First we start with a list of as in the previous entry. | + | |
- | + | ||
- | <code javascript> | + | |
- | var biblio = qc.getContentFromItems(new Array(item), | + | |
- | z.Prefs.get(" | + | |
- | var biblio_html_format = cite.html; | + | |
- | var biblio_txt | + | |
- | </ | + | |
- | + | ||
- | TODO: get citations. | + | |
- | especially RTF | + | |
- | + | ||
- | ==== 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 ' | + | |
- | + | ||
- | <code javascript> | + | |
- | + | ||
- | ==== Get fulltext for an item. ==== | + | |
- | + | ||
- | TODO | + | |
- | + | ||
- | ==== Get stored attachements for an item ==== | + | |
- | + | ||
- | TODO | + | |
- | + | ||
- | ==== Get child notes for an item ==== | + | |
- | + | ||
- | To get the child notes for an item, we use the following code: | + | |
- | + | ||
- | <code javascript> | + | |
- | + | ||
- | This returns an array of notes. | + | |
- | in turn we just iterate through the array: | + | |
- | + | ||
- | <code javascript> | + | |
- | for (var j=0; | + | |
- | var note = z.Items.get(notes[j]); | + | |
- | var note_html = note.getNote; | + | |
- | } | + | |
- | </ | + | |
- | + | ||
- | ==== Get an item's related items ==== | + | |
- | + | ||
- | This technique works for anything that can have related items attached within | + | |
- | the zotero database. | + | |
- | + | ||
- | <code javascript> | + | |
- | + | ||
- | This returns a list of items just like in the search examples. | + | |
- | + | ||
- | ==== Get an Item's Attachments === | + | |
- | + | ||
- | Here's some example code to get the full text of html and pdf items in storage and puts the data in an array: | + | |
- | + | ||
- | <code javascript> | + | |
- | var item = 'some item' ; // some Zotero Item obtained previously | + | |
- | var fulltext = new Array; | + | |
- | if (item.isRegularItem()) { // not an attachment already | + | |
- | var attachments = selected_items[item].getAttachments(false); | + | |
- | for (a in attachments) { | + | |
- | var a_item = Zotero.Items.get(attachments[a]); | + | |
- | if (a_item.attachmentMIMEType == ' | + | |
- | || a_item.attachmentMIMEType == ' | + | |
- | fulltext.push(a_item.attachmentText); | + | |
- | } | + | |
- | } | + | |
- | } | + | |
- | </ | + | |
- | + | ||
- | ===== Generic XUL Javascript to provide support functions ===== | + | |
- | + | ||
- | ==== Writing out a file: ==== | + | |
- | + | ||
- | This function will write out a file to a specified filename. | + | |
- | already exists it will be silently overwritten. | + | |
- | be cleaned up, talk about append mode as well, and failure if file already | + | |
- | exists ...] | + | |
- | + | ||
- | Note that Plain Old Webserver contains quite a few simplified support functions for reading, writing and deleting files, including new bits of javascript, and generally making things nice and easy. | + | |
- | + | ||
- | + | ||
- | <code javascript> | + | |
- | function writeFile(filename, | + | |
- | var file = Components.classes[" | + | |
- | var foStream = Components.classes[" | + | |
- | file.initWithPath(filename); | + | |
- | foStream.init(file, | + | |
- | foStream.write(data, | + | |
- | foStream.close(); | + | |
- | }; | + | |
- | + | ||
- | writeFile("/ | + | |
- | </ | + | |
- | + | ||
- | Or just use Zotero.File.putContents(str)... | + | |
- | + | ||
- | ==== TODO ==== | + | |
- | + | ||
- | many other things :) | + |