Map

Overview

A Map is a User Item that adds a map to a Custom Page. You control the map size, center point, zoom level, and map type, and you can place multiple Map User Items on a single page.^{Note 1}

You add content to the map two different ways:

1. You can use Second Site's built-in Map Editor to add markers and other shapes to the map.
2. You can add markers to the map based on your genealogy data; each Map User Item may have one or more Map Events subitems to specify which events you want to include on a particular map.

Every map may include content created either or both ways.

Maps are created by scripts that Second Site adds to the page. Those scripts use other scripts that are provided by mapping services such as Google Maps. As a result, maps will not be visible unless JavaScript is enabled in the browser. Also, the scripts depend on content that is loaded from other servers, so the person browsing the page with the map must have an active connection to the Internet or the map will not be visible.

If you publish a site on CD, and that site includes maps, you should include instructions that the maps will only work from a PC with an active Internet connection.

You can see an example map on the Second Site demonstration site.

You may adjust the formatting of the map using stylesheet parameters. In the Stylesheets.System section, see subsections that begin with "Map".

Map Editor

You can use the Map Editor to add the following types of map content, called map items, to a map:

• Markers
• Multiple-point lines (polylines)
• Multiple-point shapes (polygons)

The shapes can be either filled or unfilled. When filled, the fill is semi-transparent to allow the map content beneath the shape to show through.

See Map Editor Details for more information.

Map Events

To add markers to the map based on events in your TMG project, you add Map Events via the [Add...] button on the Edit Map window. The Add button adds a Map Events subitem to the Map User Item that appears in the Map Events list on the right-hand side of the Edit Map window. Each Map Events subitem specifies a set of events, and the locations from those events are used to create markers on the map.

Second Site only processes events that have a LatLong value assigned in the place record.

If Place Format is set to "Use Place Style", which is the default, TMG places on the map will be formatted using the assigned Place Style. When set to "Use Place SubFields", TMG places will be formatted by concatenating the place subfields together separated by ", " (comma-space). When set to "Use Short Place", TMG places will be formatted using the Short Place value (if it is not blank) or the Short Place template.

See the Map Events Details section below for a more complete description of Map Events.

Formatting

On the Custom Page, the map is enclosed by a DIV element that by default includes a border that also surrounds the map title. The specific style parameters may be adjusted via the Stylesheets.System.Map section.

You can use the Map Alignment property to control how the map is aligned relative to the other Custom Page content.

Map Properties

Title

Maps must have a Title. The title text appears above the map.

Caption

Captions are optional. If you enter a caption, it appears below the map.

Enabled

See Enabled on the User Items page.

Width

The Width property determines the width of the map on the output page. You must specify a width.

Height

The height property determines the height of the map on the output page. You must specify a height.

Map Alignment

The Map Alignment property determines how the map enclosure is positioned relative to other content on the page. The map enclosure includes the map title, the map item list, the map itself, and the map caption, if any. You can float the map enclosure left or right, or you may center it. When the map enclosure floats left or right, other content may flow to the other side of the enclosure.

Clear

See Clear on the User Items page.

Mapping Service

The Mapping Service pull-down menu determines which online mapping service will be used to create the map contents. At this time, Second Site supports Google Maps, MapQuest, Virtual Earth (aka "Bing Maps"), and Yahoo! Maps.

Note Mapping services do not support all browsers. Firefox and Internet Explorer are widely supported. Support for other browsers varies. As of this writing, Virtual Earth only supports Firefox and Internet Explorer.

Most mapping services require API Keys to publish pages that use their mapping services. Some services have different names for the API Key such as Application ID.

As of this writing, the API Keys for the services supported by Second Site are all free.

You must acquire an API Key for any mapping service you use that requires one. After acquiring the key, copy and paste the key into the appropriate text property in the User Items section of Second Site.

Service	API Key Requirement
Google Maps	A Google Maps API Key is required. See Sign Up for the Google Maps API.
MapQuest	MapQuest requires a Free Edition account or Developer account. Second Site supports the Free Edition account only. You can learn more on the Why Join page. After you signup, MapQuest provides various codes and IDs. You only need the API Keycode. The other IDs and codes are not used for the maps created by Second Site.
Virtual Earth	As of this writing, Virtual Earth does not require an API Key.
Yahoo! Maps	A Yahoo! Maps Application ID is required. See the Application ID signup form.

In most cases, the mapping service sites will include links to "How to Get Started" pages after you signup for the API Key or Application ID. You do not need to read or understand any of that information to create maps with Second Site. All you need is the API Key or Application ID. Copy and paste that data into the appropriate property in the User Items section and Second Site will take care of the rest.

The Second Site Map Editor always uses the Google Maps service. You do not need a Google Maps API Key to use the Map Editor; Google does not require an API Key when the map is rendered on a page that is loaded from a file on your hard drive.

All mapping options are not supported by all mapping services.

• MapQuest does not support terrain maps. Second Site will render a road map instead.
• Yahoo! Maps does not support polygons. Second Site will render a polyline instead.
• Yahoo! Maps does not support information windows for polylines. Any text content associated with a polyline will not be visible in the final map.
• Yahoo! Maps does not support terrain maps. Second Site will render a road map instead.

Map Style

The Map Style pull-down menu determines the map style when the page containing the map is opened. The user can change the map style using controls provided for that purpose.

The default Map Style is "Road". That produces a map that shows roads, some political divisions like town names, state and country borders, and large physical features like rivers and lakes. The other map style options include Aerial, Hybrid, and Terrain. Aerial maps are based on high-altitude photography. Hybrid maps are a combination of Road map labels and roads superimposed on Aerial maps. Terrain maps show some Road map labels but also show grade variations and other physical characterstics.

Mapping services use different names for the same map styles. The table below indicates how choices in the Map Style pull-down menu relate to mapping service map styles.

Map Style in Second Site	Map Style in Google Maps	Map Style in MapQuest	Map Style in Virtual Earth	Map Style in Yahoo! Maps
Road	Map	Street Map	Road	Map
Aerial	Satellite	Aerial Image	Aerial	Sat
Hybrid	Hybrid	Hybrid Map	Aerial (with Labels)	Hyb
Terrain	Terrain	<NA>	Shadow	<NA>

When a Map Style is not available (NA) for a particular mapping service, Second Site uses the Road style instead.

The "Shadow" Map Style is a recent addition to the Virtual Earth mapping service and as of this writing there is no way to select the Shadow style from the Virtual Earth map style control. The Shadow style features shadows that indicate grade differences, but the effect is more subtle than the Terrain Map Style supported by Google Maps.

Center Point

The Center Point property contains the geographic coordinates of the center point of the map. The person browsing the site may drag the map or use other means to change the location. You may set the value by entering a latitude, longitude value in decimal degrees notation. (See Entering Coordinates, below.) The Center Point is updated when you use the Map Editor and save the changes: the coordinates of the map center at the time you close the Map Editor are used to update the Center Point property.

If you change the center point of the map while using the Map Editor, but you want to retain the original center point and zoom level when you save the map, you can use the "Return to last result" map control. It's a small square with four inward-pointing arrows as shown in the screenshot at left. It is highlighted in yellow here, but the actual control is white.

Zoom Level

The Zoom Level slider controls the initial zoom level of the map. The person browsing the site may adjust the zoom level by manipulating the map zoom control. You may set the value by adjusting the slider. The Zoom Level is also updated when you use the Map Editor and save the changes: the current zoom level at the time you close the Map Editor are used to update the Zoom Level property.

If you change the zoom level of the map while using the Map Editor, but you want to retain the original center point and zoom level when you save the map, you can use the "Return to last result" map control as described above in the Center Point section.

Item List Position

The Item List Position pull-down menu controls whether an item list is included with the map, and if so, where it appears. The choices are "None", "Left", and "Right". The default value is "None".

If you choose "Left" or "Right", the title of each item on the map will be added to a clickable list that will appear in a list on the left or right of the map. If you choose "Left" or "Right", make sure your map is not wider than the space available in your layout.

The Second Site demonstration site includes an example map where the list of items is visible on the left.

Map Editor Details

Note You must be connected to the Internet to use the Map Editor.

To open the Map Editor, open the Map User Item and then click the [Preview and Edit] button. Second Site will display the map using a special page that includes map editing buttons. It may take a few moments for the map to appear: various files must be downloaded from the Internet to render the map and prepare the editing environment.

The Map Editor uses the Google Maps API even if you select another mapping service to render the map in the final site. If the final map will be rendered by a different mapping service, you should build the site at least once and adjust the zoom and other map parameters based on the end result rather than solely on how the map looks in the Map Editor.

To draw on the map, click on one of the editor buttons in the top left of the window and then click on the map.

Markers are created with a single click. To edit the name of a marker, and other properties, click the marker to open the map item dialog.

Lines and polygons require multiple clicks to define the ending point of each segment. Double-click to stop drawing a line or polygon. For polygons, the last point will automatically be connected to the first point.

To edit an existing item and change its name, line width, color, etc., click on the item or click on the name of the item in the list of items.

To change the sequence of the items in the list, click on the item and while holding the mouse button down, drag the item to the position you want and then release the mouse button.

To edit a line or polygon, mouse over it and drag the points. While editing points, click on a point to delete it. You can click on the "ghost points" to add a vertex between existing vertexes. The ghost points lie halfway between the existing vertexes.

To add a vertex to either end of a line, move the the last vertex to the new desired end point. Then click on the ghost handle that is between the last two vertexes and drag it to where the old end used to be. That will create a new vertex there. The result is the addition of a new point on the end, but done by adding one in the middle. This method is necessary because there is no ghost handle you can use to create a point beyond the current end point.

To add a line that connects markers, you have to overcome the problem that clicking the mouse near a marker will select the marker and that interferes with drawing a line. The solution is to click near the desired location and then go back and drag the vertex to the desired location. To begin, click on the polyline tool, and then click near (but not on) the first marker. The Map Editor will create the first vertex and show a "rubberband line" and the "X" cursor for making the next vertex. Continue in that fashion until you have all the line segments you want: click near but not on the markers. After double-clicking to end the addition of new vertexes, move the mouse over the first vertex in the line. Click and drag the vertex handle over the marker. Repeat that for the other points on the line. When moving the line vertexes, you'll probably want to be fully zoomed in so that the line vertexes are very, very close to the points they share with the markers.

To close the Map Editor, click the [OK] button or the [Cancel] button. The [OK] button will close the window and update the Map User Item. The [Cancel] button will close the window and discard any changes. If you close the window using the close box in the upper-right of the window, Second Site will ask you if you want to update the map to match the current window contents. To save the change, click [Yes] or press enter.

Map Events Details

Each Map Events item includes a series of properties.

Icon

Click the [Set Icon] button to select the icon you want to assign to the event locations. Click the [Standard] button to use the default icon determined by the mapping service. The other icons are colored and/or numbered icons based on the Google Maps icon style.

If you choose an icon with a number, all the locations will be assigned that icon. If you click the [Numbered] button, Second Site will assign icon "1" to the first place, icon "2" to the second, etc.

To match icons to other graphic elements, it may help to know the exact colors of the markers. None of the markers are a single solid color, but the following colors are close.

Color Name	Color Value
red	#FD645C
orange	#FF9109
yellow	#FEF500
green	#4DEB1C
dark green	#3F9405

Color Name	Color Value
blue	#0677FB
light blue	#01DBF6
purple	#B705F9
pink	#FF00EF
black	#000000

Show Coordinates

If Show Coordinates is checked, the information box for the location will include the latitude and longitude coordinates. The default value is checked.

Show Place Comment

If Show Place Comment is checked, the information box for the location will include the Comment field from the TMG Place Record. The default value is unchecked.

Event Filters

For each Map Event item, you specify one or more filters to select a subset of TMG events:

• by Event Type (Birth, Death, Burial, etc.)
• by Event Primary status
• by Person (by a custom flag value)
• by Location (filtering based on city name, state name, etc.)

The filters are applied in the following sequence:

1. As described above, the location must have a LatLong value assigned. Second Site does not geocode locations for various reasons.
2. Location filter: Second Site applies the location filter, if any, and ignores locations that do not pass the filter.
3. Event Type filter: Second Site checks the Event Type of each event that took place at the given location. If you choose an Event Type from the Map Event item's Event Type pull-down menu, then the event must have the same Event Type. If you do not choose an Event Type, then the event must have an Event Type that is selected in the Database.Tags list of events.
4. Event Primary filter: If Primary Only is checked, the event must be primary for both principals or the event will not be processed.
5. Living filter: The event is subject to the People Section Detail Filters, so events for living people may be suppressed.
6. Included/Excluded filter: One of the event principals must be included on the site or the event is ignored.
7. Flag filter: Second Site applies the flag filter, if any, and ignores events if neither principal passes the flag filter. Only one principal must pass the filter, not both.

Place Filter Values

In the Value fields in the Place Filter section, you can enter multiple values separated by two vertical bars. So, for example, to test for multiple States:

• Set Place Subfield to: L5 - State
• Set Operator to: Equals
• Set Value to: Iowa||Ohio||Utah

With the Operator set to "Equals", as shown above, any one of the three states is a valid entry for the State field. Second Site constructs the logical filter as follows:

State = "Iowa" OR State = "Ohio" OR State = "Utah"

If you change the Operator to "Does Not Equal", then any one of the three states is an invalid entry and all other states are valid. Second Site constructs the logical filter as follows:

State != "Iowa" AND State != "Ohio" AND State != "Utah"

("!=" is a two-character symbol used to mean "not equal".)

Show Label

If Show Label is checked, the event label will be included in the marker text. The marker text always includes the date (if any) and the principal names.

Connecting Markers with Lines

You can connect the events defined by a Map Events entry using the Add Line checkbox. When checked, Second Site will add a Polyline that connects the markers. You can choose the line color and line width using the associated controls.

Coordinates

Entering Coordinates

For places that you specify when you define a map in Second Site, such as the initial center point of the map, you enter coordinates using decimal degree notation. In decimal degree notation, both the latitude and longitude are expressed as decimal numbers with fractions of a degree after the decimal point. Positive numbers for latitude are north of the equator, and negative numbers are south. Positive numbers for longitude are east of the Prime Meridian, negative numbers are west.

For example, here is the latitude and longitude of the pitcher's mound at Fenway Park in Boston, Massachusetts: 42.346351,-71.097615. (Map)

Decimal degree notation is used by most GPS devices and by all the major online mapping services.

Latitude and longitude can be entered in your TMG data in the LatLong subfield of the Place Record. TMG supports a special format for entering this data. You can read about the TMG format in the TMG help system.

You can enter decimal degree notation in TMG's LatLong field, but as of TMG Version 7.01, TMG will convert that format into its internal format. TMG's internal format is not as precise as the decimal degree notation, so some precision is lost during the conversion. For example, if you enter the pitcher's mound location (42.346351,-71.097615), the converted coordinates will equate to 42.346111,-71.0975 (Map), a spot near the Red Sox dugout, not the pitcher's mound.

For that reason, Second Site recognizes an alternate format for entering decimal degrees notation in TMG. Use a tilde ("~") in place of a comma to separate latitude from longitude, i.e, 42.346351~-71.097615 in place of 42.346351,-71.097615. TMG will not convert that format to its internal format, but Second Site will recognize the value as a pair of decimal degrees notation LatLong values.

Latitudes in the southern hemisphere begin with a minus sign. To avoid confusion with TMG's single-exclusion marker, you can add a tilde as the first character in the coordinates. So, for example, coordinates for Lima, Peru are ~-12.092115~-77.046604 (Map).

Note I have asked to Wholly Genes to consider officially supporting the tilde-based notation and they are considering it. As of TMG v7.03, you can enter the coordinates with tildes as described. TMG will warn you that the text is not a valid LatLong value, but you have the option of telling TMG to accept the data as-is.

Determining Coordinates

If you have a handheld GPS device, you can find the coordinates of any place you can visit, and you probably know how to do so. Some automobile direction systems will display the coordinates of the current location, although some make the coordinates more prominent than others.

If you do not have a GPS device, or you are unable to visit the desired location, you can use various online web sites to determine the coordinates. Some of those sites are listed below. Some of the sites are applications built on one of the major mapping services such as Google Maps, Yahoo! Maps, etc.

The Yahoo! Maps site has a good interface for displaying the coordinates of a certain location. The map includes a cross-hair display that shows the center point of the map, and the URL in the address bar of the browser shows the latitude and longitude of the center point of the map, ...&lat=42.66565&lon=-71.071823 (Map), for example. Position the map so that the cross hairs are over the location, then copy the coordinates from the URL.

Some mapping services have better maps than others for certain areas. If you do not want to use the Yahoo! Maps page to determine location coordinates, try one of the following tools. Careful! Some tools display the coordinates in Longitude, Latitude sequence rather than the more prevalent Latitude, Longitude seqence.

• Google Maps – Easy to use to find the location of interest, but it takes a couple steps to display the coordinates. (See the Determining Coordinates using Google instructions below.)
• iTouchMap – Somewhat difficult to use because it adds markers everytime to click the map, even when you are still trying to move the map to the area of interest.
• GPS Coordinate Finder – Easy to use, but it displays the coordinates in "Longitude, Latitude" sequence which complicates the cut/paste process.

The Second Site Map Editor shows the coordinates of the center point of the map beneath the map. That may be helpful, but it does not include a crosshair or other graphic device to indicate where the center is, so it is not useful for precise work.

Determining Coordinates using Google

Follow these steps to extract the coordinates of a location using the main Google Maps site. These instructions have been tested using Firefox 2, Firefox 3, and IE7. As of June 2008, Opera does not support the right-click context menu for Google Maps and therefore this procedure will not work.

1. Enter an address and let Google search for it. If Google Maps does not know the specific location, enter the location of a place nearby.
2. Drag the map, and zoom in as close as possible until you can see the location of interest.
3. Right-click on the exact spot and choose "Center map here" from the pop-up menu.
4. Click the "Link to this page" link that is above the map on the right.
5. Google Maps will open a small sub-window that includes a link in the top textbox. Copy and paste the link into a text editor.

   The link text will look something like this:

   http://maps.google.com/maps?f=q&sll=37.09024,-95.537109
&sspn=47.751524,83.320313&ie=UTF8&ll=42.346352,-71.097613
&spn=0.000685,0.001271&t=h&z=20

6. Find the coordinates in the link.

   The coordinates of the center point of the map are after "&ll=" (ampersand-ell-ell). In the link above, the coordinates are "42.346352,-71.097613". Ignore the other parameters that look like coordinates.

Notes

1. You may include multiple maps on a Custom Page. It's possible to include maps from different mapping services on the same page, but that is not recommended.