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.
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.
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.
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.
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.
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...
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
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.
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.
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.
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://mapsURI toui.html, which provides the main visualization interface of Zotero Maps.- Using the Zotero API,
initcreates a new local SQLite database, with a single table,cache, used to store geocoding results from geonames.org.- Also, using the Zotero API,
initregisters thenotifierCallbackmethod to be called when new items are added to the Zotero collection, so that they can be geocoded according to theirplaceattribute 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.
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.
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.
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.
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!