**Note:** The API described here is the only recommended and supported method of //modifying// Zotero data. External //read-only// access, however, is supported. For more information on external access, see [[Accessing Zotero Data Using an SQLite Client]].


====== Helpful Resources ======



For this section, you’ll likely find the following helpful:

  * [[Overview of Zotero and the Technologies It Uses]]
  * A basic understanding of how to create a Firefox extension
    * [[http://developer.mozilla.org|The Mozilla Developer Center]] (including [[http://developer.mozilla.org/en/docs/Building_an_Extension|Building an Extension]])
    * [[http://kb.mozillazine.org/Setting_up_extension_development_environment|Setting up an extension development environment]]
      * We don’t recommend enabling //nglayout.debug.disable_xul_cache//, as it seems to wreak havoc in Firefox 2.0, but //javascript.options.showInConsole// is a requirement
  * A decent grasp of object-oriented JavaScript
    * [[http://javascript.crockford.com/private.html|public, private and privileged methods and members]]; object literal notation; closures
    * [[http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference|MDC Core JavaScript 1.5 Reference]] (also note [[http://developer.mozilla.org/en/docs/New_in_JavaScript_1.6|New in JavaScript 1.6]] and [[http://developer.mozilla.org/en/docs/New_in_JavaScript_1.7|New in JavaScript 1.7]])
  * A bookmark to [[http://www.xulplanet.com|XULPlanet.com]]


====== The Zotero Object =====

Zotero exposes an object-oriented data API that can be used to access and modify Zotero data. Within Zotero itself, most SQL statements are limited to the data layer, with all other elements (including the entire UI) using the data API to access the data. Through [[ overview_of_zotero_and_the_technologies_it_uses#xpcom|the base Zotero XPCOM service]], this functionality is available to all privileged code in Firefox, including other loaded extensions.

To access the data API in your own extension, you will need access to the core Zotero JavaScript object. If your extension operates within the main browser overlay, you already have access to the ''Zotero'' object and don’t need to take further steps. Otherwise, you can import the Zotero object into other windows either by including the script %%chrome://zotero/content/include.js%% within a XUL file (recommended) or by manually calling ''getService()'' directly on the Zotero XPCOM service and assigning the wrapped JS object to a variable.

%%chrome://zotero/content/include.js:%%
<code javascript>
var Zotero = Components.classes["@zotero.org/Zotero;1"]
				.getService(Components.interfaces.nsISupports)
				.wrappedJSObject;
</code>






====== The Zotero Data API ======

Once you have access to the core Zotero object, you can use the objects and methods provided by the Zotero data API.

Note: We’ll be updating this site with more detailed API documentation in the near future, but in the meantime, the commented code itself---in particular chrome/content/xpcom/data_access.js---is the best resource for understanding the API.

Zotero uses a combination of instantiatable objects (e.g. ''Zotero.Item = function(){...}'') and singletons (''Zotero.Items = **new** function(){...}''). The most important example of the former is ''Zotero.Item'', which represents a single item in the database. Singletons are used mostly to group related static methods into a single namespace.

A typical operation might include a call to ''Items.get()'' to retrieve an ''Item'' instance, calls to ''Item'' methods on the retrieved object to modify data, and finally a ''save()'' to save the modified data to the database.

<code javascript>
var data = {
    title: "Much Ado About Nothing",
    creators: [
        ['William', 'Shakespeare', 'author']
    ]
};
var item = Zotero.Items.add('book', data);
var itemID = item.id;
</code>

<code javascript>

// Fetch saved items with Items.get(itemID)
var item = Zotero.Items.get(itemID);

alert(item.getField('title')); // "Much Ado About Nothing"

alert(item.getCreator(0)); // {'firstName'=>'William', 'lastName'=>'Shakespeare',
                           //   'creatorTypeID'=>1, 'fieldMode'=>0}


item.setField('place', 'England');
item.setField('date', 1599);
item.save(); // update database with new data

</code>




====== Notifier ======

Zotero has a built-in notification system that allows other privileged code to be notified when a change is made via the data layer---for example, when an item is added to the Library. Within Zotero itself, this is used mostly to update the UI when items change, but external extensions can use the system to perform additional operations when specific events occur---say, to sync item metadata with a web-based tool.

Available events:

  * add (c, s, i, t, ci, it)
  * modify (c, s, i, t)
  * delete (c, s, i, t)
  * remove (ci, it)
  * move (c, for changing collection parent)

c = collection, s = search (saved search), i = item, t = tag, ci = collection-item, it = item-tag

See the [[sample_plugin|sample Zotero plugin]] for a demonstration and some ideas for potential utilities.