=========== Zotero Maps

Introduction

Welcome to Zotero Maps, a plugin for displaying your Zotero_ collections on a map in your Firefox web browser.

Zotero Maps uses OpenLayers_ to display geographic markers associated with your Zotero items on a map in Firefox. The locations of these markers are generated by taking the value of the place field for each item, and sending it to the GeoNames_ API to get a latitude/longitude coordinate. Items associated with the same place name are grouped together on the map. The background map used in Zotero Maps comes from the OpenStreetMap_ project.

Zotero Maps is Free and Open Source software, and is distributed under the same terms_ as Zotero itself.

Users' Guide

This Users' Guide for Zotero Maps presumes that you already have Zotero installed and are familiar with how it works. Additionally, we assume that you have already added a few items to your Zotero library.

Installation

Installing Zotero Maps is very simple: Open the `Zotero Maps extension`_ in
your Firefox browser. You will be prompted to confirm the installation and
restart your browser. Please note that you must have a working Internet
connection when using Zotero Maps for it to work properly.

General Use
~~~~~~~~~~~

Once you've restarted Firefox, open Zotero, and browse around your library
until you find an item or a collection containing items that have the *place*
field set. Select this item or collection by clicking on it, then go to the
*Actions* menu (the dropdown menu in the Zotero window with the 'gear' icon),
and click on *View as Map*.

A map will open in your browser window. Since this is presumably the first time
you have used Zotero Maps, a spinner will be displayed while the locations of
your items are being looked up in the GeoNames_ database.  This may take a
while, particularly if your collection is large, so please be patient.

Once all the items have loaded, the spinner will disappear, and you can
browse the items on the map. You can pan by dragging the map with your mouse,
and zoom in and out using the controls on the left hand side of the map. You
can also zoom in by double-clicking on the map.

Click on one of the place markers. A balloon will pop up, showing the name of
the place, and how many items are associated with it. Additionally, the items
associated with that place will be listed underneath it. The title of each item
is hyperlinked, so you can click on it to open that item in Zotero, and view
its details. Clicking the 'X' button in the balloon, or clicking on the marker
will cause the balloon to close.

Congratulations, you're using Zotero Maps! From now on, you can select your
whole library, a single collection, or one or even multiple items, and go to
*Actions -> View as Map* to see them displayed in Zotero Maps.

Considerations

The locations fetched from GeoNames are cached in your Zotero data directory, so that the next time you open the map, they should display instantly. Also, after you install Zotero Maps, items will be looked up as they are added to your library, which should also reduce the map loading time in the future.

Please note that it is quite likely that not all of the items you have selected will appear on the map. If this is the case, it is likely that the place field is not set on the item in question, or that GeoNames couldn't figure out where in the world it referred to. Try editing the place field on that item and try loading the map again.

One other note of warning: Due to the limitations of Firefox, only about 100 different items can be displayed in Zotero Maps at once. If you have a large collection and would like to see this corrected in a future version of Zotero Maps, please contact us_.

Acknowledgements

Zotero Maps was built by Entropy Free LLC, with the support of the Center for
History and New Media. Schuyler Erle and Tim "Chippy" Waters wrote most of
the code, with assistance from Swapnil Hajare, Kanhaiya Kale, and others.

If you like Zotero Maps and find it useful, please consider supporting any of
the great projects on which Zotero Maps is built, e.g. Zotero_, OpenLayers_,
OpenStreetMap_, or GeoNames_. All four of these terrific projects provide Free
and Open software or services to the community, and deserve your support.

If you would like to see Zotero Maps improved, please feel free to `contact
us`_ with your ideas, comments, suggestions, bug reports, et cetera. If you
would like to provide financial support for the development of specific
features, please `contact us`_. If you would like to contribute code to Zotero
Maps, please read on...

-----------------
Developers' Guide
-----------------

We specifically invite Free and Open Source developers to contribute
patches to Zotero Maps. What follows is a walk through the code for anyone
interested in improving or extending Zotero Maps.

We presume that you have a working knowledge of JavaScript, Zotero,
and Firefox extension development generally. Before continuing, please
be sure that you have read and are familiar with:

  * Zotero's `Getting Started`_ guide for developers
  * Zotero's `development documentation`_ generally
  * The Zotero Maps `Users' Guide`_

Overview
~~~~~~~~

The Zotero Maps code base is structured like a normal Zotero plugin in most
respects. The ``install.rdf`` and ``chrome.manifest`` files in the top-level
are exactly what you'd expect.
    
The core plugin code all lives in ``chrome/content/zotero-maps/``, while the
static content is in ``chrome/skin/default/zotero-maps/``. One exception is the
OpenLayers library, which does not require Firefox extension privileges at
runtime. Consequently, the library lives in the ``skin/`` directory, along with
its static content.

A ``Makefile`` is included with the distribution. We use this to build the
``.xpi`` file. We don't package up the chrome directory as a ``.jar`` file;
please let us know if you can suggest a particular reason why we should.

overlay.xul
~~~~~~~~~~~

The ``overlay.xul`` file defines the UI overlay for the Zotero Maps plugin. It
sets up a single menu option in the tools dropdown, and calls ``include.js`` to
bootstrap the plugin at load time.

include.js
~~~~~~~~~~

The ``include.js`` file creates a core ``Zotero`` object using the XPCOM API.
Additionally, it loads the OpenLayers library, and loads ``setup.js`` to
initialize the Zotero Maps plugin.

setup.js
~~~~~~~~

The ``setup.js`` file contains the definition of the ``Zotero.Maps`` singleton
object that provides the core functionality of the Zotero Maps plugin.


The ``init`` method of the ``Zotero.Maps`` object configures the plugin:

  * With the Mozilla XPCOM API, it maps the ``zotero://maps`` URI to
    ``ui.html``, which provides the main visualization interface of Zotero
    Maps.
  * Using the Zotero API, ``init`` creates a new local SQLite database,
    with a single table, ``cache``, used to store geocoding results from
    geonames.org.
  * Also, using the Zotero API, ``init`` registers the ``notifierCallback``
    method to be called when new items are added to the Zotero collection,
    so that they can be geocoded according to their ``place`` attribute
    immediately, if possible.

The ``get`` and ``set`` methods wrap access to the ``cache`` table. The
name, latitude, and longitude from all geonames results are stored there.

The ``query`` method is used to perform lookups against the Geonames API,
using the OpenLayers XML HTTP request API. The request is asynchronous, so
the results are passed to the ``query_callback`` function. If the API
lookup yields results, the results are stored in the cache, and, if a UI
callback was provided, it's then called with the result. 

Typically, the Geonames API returns multiple matches for a given place
name, order more or less by importance. The first query result is used by
Zotero Maps by default, as it's usually the one intended. If Geonames
couldn't identify the place name, the place is cached with the coordinates
(0,0), to mark it as unknown. A future version of Zotero Maps should
provide a user interface to allow the user to choose from the full list of
Geonames query results, or to allow manual correction, if the first result
returned should turn out not to be the one intended.

Finally, the ``load`` method of the ``Zotero.Maps`` object provides the
hooks for the integration with the Zotero UI in ``overlay.xul``. The logic
for deciding what to display on the map is as follows:

  * If one or more particular items are selected in the Zotero UI, map them.
  * If a collection is selected, map the items in it.
  * If a saved search is selected, map the items in it.
  * Otherwise, attempt to map the entire library. 

ui.html
~~~~~~~

The ``ui.html`` file provides the main visualization interface for the
plugin, which is a very basic OpenLayers application. It loads OpenLayers
and plugin-specific CSS from the ``skin`` directory, and then loads the
Zotero Maps API, the OpenLayers API, and the Zotero Maps UI code, in that
order. Since this file loads ``chrome://`` URLs, it is kept in the
``chrome/content/`` directory, in order to have permissions to do so.

ui.js
~~~~~

The main Zotero Maps UI code lives in ``ui.js`` and provides the map
display and interaction.

The ``onLoad`` function is called by the browser when ``ui.html`` loads.
This function creates an ``OpenLayers.Map`` object, and configures it with
various UI controls, including pan/zoom, keyboard and mouse navigation,
base map attribution, and the loading spinner. The map is configured to
display in the global spherical Mercator projection, to match the
OpenStreetMap tiles used as the basemap. (Note that this is the same
projection used by Google Maps.)

The ``populate_map`` function is called by ``onLoad`` to fetch the selected
items from Zotero, and display them on the map via
``lookup_item_for_features``. This function looks up the items in the cache
via the Zotero Maps API described above, and, when item places are not
present, uses the API to query the place names on Geonames and cache them.

As each item is loaded, ``add_item_to_features`` is called. This function
creates a marker on the map for each coordinate pair, if one isn't already
present, and adds the item to the popup listing for that marker. If a
marker is already present at that location, the item is simply added to the
list. Each marker is created with a UI callback that opens a popup balloon
showing the list of items matching the marker's location. Each list item is
hotlinked to its entry in the Zotero UI, so that clicking on an item listed
in a popup balloon opens its details in the Zotero panel.

OpenLayers
~~~~~~~~~~

The current version of Zotero Maps ships with a custom build of OpenLayers
2.7. The build configuration is kept in a file called ``zotero.cfg`` in the
Zotero Maps source tree. The loading panel code comes from the OpenLayers
``contrib`` SVN tree, and was added manually to the OL source tree prior to
building the compressed version of the library.

Patches
~~~~~~~

We wholeheartedly welcome developers to `contact us`_ by email to submit
patches to Zotero Maps. Feature and bug fix submissions should by and large
follow the same JavaScript coding conventions used in the current code base.
Thank you in advance for your interest!


.. _Zotero: http://www.zotero.org/
.. _OpenLayers: http://www.openlayers.org/
.. _GeoNames: http://www.geonames.org/
.. _OpenStreetMap: http://www.openstreetmap.org/
.. _`same terms`: http://www.opensource.org/licenses/ecl1.php
.. _`Zotero Maps extension`: http://zotero.entropyfree.com/download/zotero-maps.xpi
.. _`Getting Started`: http://www.zotero.org/support/dev/getting_started
.. _`development documentation`: http://www.zotero.org/support/dev/start
.. _`contact us`: mailto:[email protected]