Creating and Editing EventMaps
Work on this project has been supported by the
NEH Digital Humanities Fellowship FX 50009 08
with additional support from Colgate University.
Outline
- EventMap Applications
- The Structure of the Spreadsheet: table pairs
- From Spreadsheet to Application
- Editing the Application
EventMap Applications
An EventMap application consists of a sequence of events located in space and time and annotated with web pages. (See the MAPs site for examples.) To create such an application, the following kinds of information are needed:
- The title of the application, its date of creation or last revision, the creator(s), and a description. The description will become a "greeting page" that will appear in the annotation space when the application is invoked.
- A list of events, each with a title, start date, end date (can be the same), location and its coordinates, and a description. Other attributes can be added, as explained below.
- Additional information on how the events are to be displayed on the map. The kinds of displays available are: points (markers), polylines, polygons, and overlays. Markers, polylines and polygons can be color-coded according to the values of some event attribute. For markers, the creators can contribute their own set of icons to be displayed on the map. For overlays, the creators must provide a set of images that will become "ground overlays" on the map.
All this information can be presented in a Google spreadsheet from which the application is automatically compiled. The spreadsheet can be created directly in the browser as a Google Spreadsheet, or as an MS Excel document to be imported into Google.
top
Creating an EventMap Application: Outline
The main steps in creating an EventMap application are as follows.
- Create a Google spreadsheet that defines the application. The structure of the spreadsheet is described in the next section. For now, we only note that cell A1 must contain an ID for the application that is unique within your EventMap folder. (It is, of course, possible to have more than one EventMap folder on the same website.)
- Publish your spreadsheet as an ATOM feed. (See explanations and detailed instructions in the Google to JSON section below.
- Unzip the EventMap archive to create your EventMap folder, initially containing no applications.
- Create a subdirectory of your EventMap website whose name is the same as the ID in cell A1 of the spreadsheet.
- Run the Google2JSON program (in the script directory of the EventMap folder) to create the JSON text that defines your application. The text will be stored in a file called config.js in the folder for your application.
The rest of the work in preparing your EventMap is similar to authoring in the traditional scholarship sense: creating texts, possibly with images and multimedia, to express the content you wish to express.
The structure of the spreadsheet
The spreadsheet that defines an application must consist of one or more pairs of tables. The first such pair defines the basics of the application as specified in points 1 and 2 above. Additional pairs of table provide additional information. The first table in each pair has exactly two lines in it that provide metadata (attributes and their values) for the table that follows. We will call those two-row tables metatables. The first attribute of a metatable is id. It identifies this particular pair of tables .Tables are separated from each other by one or more blank lines.
Application Description and Event Descriptions
The most important table pair, and the only one that is required, is the first pair. Its metatable usually goes in rows A and B starting in column 1. Its first line lists the attributes of the entire application (as specified in item 1 above) and their data types. For instance, it may look like this:
| id:text | title:text | date:text | creator:text | description:single |
| Unique ID | Chronicles of Trivia | 2008-03-17 | Jane Doe; Joe Schmoe | This sequence of maps shows the major battles of the War of the Trivial Succession; consult Trivia websites for more detail. |
Notes:
- The text data type is the default and can be omitted.
- The difference between text and single is that cell contents in single columns can contain semicolons. In columns of type text, semicolons indicate a sequence of items.
- The id must be non-empty, and its value must be unique in the entire EventMap website. It may not contain punctuation, spaces, or the & character. In this example it will be apChroniclesOfTrivia. By convention, we begin application's ids with "ap," followed by the title run together, with each component word capitalized. Some people might prefer underscores: ap_Chronicles_Of_Trivia, with or without capitalization. This is entirely the matter of personal preference, as long the id is a legitimate directory name, and is unique in the website.
- The date can be YYYY or YYYY-MM or YYYY-MM-DD, as in the example. In any case, it should be of data type "text," not "date." In practice, this means that it needs a single quote in the beginning. The quote will not show, but the data will be stored as text.
- If there is more than one creator, their names must be separated by semicolons.
- The description can be in one of three possible formats:
- a paragraph of plain text, as in the example;
- text with HTML markup: anything that can be placed in the <body> element of a web page;
- a URL that begins with http://
The Events Table
After a blank line, the second table defines events as specified in item 2 above. Its first line lists the attributes of events and their data types, with text as default. The lines that follow define events, one per line. For instance:
| label | title | start | end | location | lat:number | lon:number | description:single |
| FirstBattle | First Battle | 1245-10-22 | 1245-11-20 | The Central Plateau | 155.2 | 73.11 | The First Battle lasted more than a month and resulted in a draw. |
| SecondBattle | Second Battle | 1247-11-04 | 1247-12-07 | The Slippery Slope | 149.5 | 73.22 | The Second Battle effectively ended the war. |
top
This example shows the minimal number of attributes. The label field must be a word or short phrase that is unique within the label column of this table. (The id of the previous table must be unique within the entire website.) If two labels are the same, the program will add a suffix to them to make them unique: FirstBattle_a, FirstBattle_b.
top
The start and end date fields follow the same conventions as the date in the first table. In this application there are two coordinate fields (lat and lon) because this application is about point events. The description field offers exactly the same options as the corresponding field in the first table.
Additional Attributes
Many applications have additional attributes. An eventType attribute is frequently useful for classifying, color-coding and filtering events so that only events of a specific type are displayed. See the MAPs site for examples of additional attributes.
Polylines, Polygons, and Overlays
If your application displays polylines or polygons for each event, you need to specify the geometry (polyline or polygon) in the metatable, and a sequence of points for each event. The convention for specifying a sequence of points is to create a single column called points for coordinates (not two columns, as in the example above); each cell in that column will contain a sequence of lat-lon pairs with spaces between the numbers within each pair and semicolons between pairs, e.g.,
34.2 73.5; 29.87 70.18; 30.99 75.6
If you have an "event" unfolding in discontinuous regions (polygons) then we have to consider it as a collection of simultaneous events described on separate lines of the spreadsheet.
For overlays, which are rectangular images that are superimposed on the map, you need four columns labeled North, East, South, West, to indicate where the image is placed.. You also need to provide a URL or local file reference for the image. Note that Google maps cannot handle overlays specified by four points (four pairs of coordinates) that do not form a rectangle.
top
Geocoding and Georeferencing
The process of finding coordinates for locations is called geocoding. The process of matching the corners of an overlay to specific points on the map is called georeferencing. Both kinds of data can be specified in the events table of the application or they can be placed in a separate table pair as the next section explains.
Other Table Pairs
Other table pairs follow the same metatable - table pattern. They provide additional information, such as icons to use for map markers or geodata information for place names. Several id's are reserved for common uses. Their names always begin with the underscore character, e.g., _icon. Here is an example of a geocoding table:
| id | ||
| _lat:lon | ||
| placeName | lat | lon |
| Kabul;Kabol | 34.533 | 69.166 |
| London | 51°30'28"N | 0°07'41"W |
Notes:
- This table assumes that your column of place names in the events table is labeled "placeName." If your label is "Location" then this is what you would put in the additional table. In general, the label of the first column of a reserved-name table should repeat one of the labels in the events table.
- The column of place names, both here and in the events table, can give alternative spellings separated by a semicolon.
- The coordinates can be given as fractions or as degrees-minutes-seconds, but it is of course preferable to be consistent within an application.
top
From Spreadsheet to EventMap
If the spreadsheet has been prepared in Excel, the first step is to import it into a Google spreadsheet.
The Google spreadsheet is processed by the Google2JSON program (see next section) that converts its content into the JavaScript Object Notation (JSON) format.
The JSON text is parsed by the EventMap program to create the EventMap application.
In the EventMap application, titles and descriptions will appear as a web page in the annotation space on the left. There is some default formatting applied to it that can be overridden by a stylesheet or explicit markup. Map-related elements of the spreadsheet will appear as Google map overlays (markers, polylines, polygons, ground overlays).
Google to JSON
In more precise detail, Google Spreadsheets can be published the way blogs are published, in the XML format called Atom. This is known as "an Atom feed." To create an ATOM feed for your spreadsheet proceed as follows:
- Click the Share button in the top right area of your spreadsheet. Select the "Publish as a Web page" option.
- In the open dialog window, check the box that says "Automatically re-publish when changes are made." Under "What parts" select "Sheet 'Sheet1' only."
- Do not take any other actions in this dialog window except to click the link to "More publishing options" on bottom left.
- In the next dialog window, two important actions must be takes. First, click the File Format dropdown list and select ATOM. The window will change to show another option, Feed Format, with two radio buttons. It is essential that you select Cells, not List.
At this point, you are ready to generate the URL for your ATOM feed. Click the Generate URL button, and select and copy the generated URL. Close the dialog window and proceed to the script sub-folder within your EventMap application folder. Click on Google2JSON.html. The page will show a blank text area and an input text box under it that says "Paste Spreadsheet Feed URL here or select from the list below." Paste the URL you have copied from the Google spreadsheet into the input box and click Submit Query. The textarea will contain the text for your config.js file. Click in the textarea, Select All, and Copy. Open a text editor (Notepad, Textpad, Wordpad, BBEdit), paste the contents of the text area and save as the config.js file in your EventMap application folder. Your application is ready to use.
If your spreadsheet is edited then you have to re-generate the config.js file. For that eventuality, you should save the URL of your spreadsheet's ATOM feed somewhere. The best way to do it may be to add it to the dropdown list on the Google2JSON page. Next time your spreadsheet is edited, open the page, select your spreadsheet and click Submit Query. As before, copy the contents of the textarea, and paste them into your config.js file, replacing its earlier content.
Technical Note
Google Spreadsheets have a programming interface that makes it possible to collect the data from the field and process it upon receipt by a function that is automatically invoked when the data arrives (a "callback function"). This centerpiece function converts Atom XML data into a structured text in the formal notation called JSON (JavaScript Object Notation). EventMap components, including the TimeMap and the annotations, work from this JSON text. It can be found in the file config.js in each application directory.
All EventMap code is free and open source.
Editing the Application
Google spreadsheets can be shared with other users, giving them rights to change the application. Two most common actions are: add an event (a row in the spreadsheet), or edit an event description. This can be done directly in the shared spreadsheet. We are working on a convenient user interface to submit data for entering into the spreadsheet.
top