Map User Item

Overview

A Map is a User Item that adds an interactive map to a Page.

A Map is a Content Item and does not create a page of its own. You must add it to a Page User Item or you will not see its content. You may add multiple maps to a single page.^{Note 1}

GedSite uses either the Bing Maps or Google Maps mapping service to render the map. You must acquire an API key from the mapping service to use the Map User Item. See the notes in the Map Service section, below.

Second Site creates maps that are very similar to GedSite's maps. You can see an example map on the Second Site demonstration site.

You add content to the map two different ways:

1. You can use GedSite's built-in Map Editor to add markers and other shapes to the map. Use the Map Editor > Edit Map... command in the Edit Map Item window to open the Map Editor.
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 the map. Your genealogy program must provide a place to enter the latitude and longitude of the place associated with an event, and the program must include the latitude and longitude in the GEDCOM export file.

Every map may include content created either or both ways.

Maps are created by scripts that GedSite 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 removable media, and that site includes maps, you should include instructions that the maps will only work from a computer with an active Internet connection.

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.

The GedSite Map Editor always uses the Google Maps service. The map GedSite creates for your site will use the Map Service you choose.

When you Edit or Preview a map using the Map Editor, you will not see any markers that are added via the Map Events item(s). Those markers are only added when GedSite makes the map as part of making the site.

See Map Editor Details for more information.

Map Events

To add markers to the map based on events in your GEDCOM file, you must add at least one Map Events item to the Map Events list in the Edit Map Item window. Each Map Events subitem specifies a set of events, and the locations from those events are used to create markers on the map.

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

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

Map Item Properties

Title and Show Title

Maps must have a Title, but the Title may or may not appear on the page. If Show Title is checked, which is the default, the title text appears above the map.

Enabled

See Enabled in the Common Properties section of the User Items help page.

Caption

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

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.

Page Section

See Page Section in the Common Properties section of the User Items help page.

Alignment

The Alignment pull-down menu controls whether the item appears inline, floats left, is centered, or floats right. When floated left or right, any subsequent content will flow around the item on the opposite side. The item includes the map title, the map item list, the map itself, and the map caption, if any.

Clear

See Clear in the Common Properties section of the User Items help page.

Class

The Class textbox allows you to specify the name of a CSS class that will be added to the map's container. You may use the class in the selector of a User Style to customize the appearance of any Map User Items with the specified class name.

Map Properties

Map Service

The Map Service pull-down menu determines which online mapping service will be used to create the map contents. At this time, GedSite supports Bing Maps and Google Maps.

Note Mapping services do not support all browsers. Edge, Firefox, Google Chrome, Internet Explorer, and Safari are widely supported. Support varies for other browsers.

Both mapping services require API Keys to publish pages that use their mapping service. The services refer to the API keys using varying names such as API Key or Application ID. As of this writing, the API Keys for the mapping services supported by GedSite are all free.

You must acquire the API Key. After acquiring the key, copy and paste the key into the appropriate text property in the API Keys section of GedSite.

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 GedSite. All you need is the API Key or Application ID. Copy and paste that data into the appropriate property in the API Keys section and GedSite will take care of the rest.

Map Type

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

The default Map Type 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 type 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 types. The table below indicates how choices in the Map Type pull-down menu relate to mapping service map types.

When a Map Type is not available for a particular mapping service, GedSite uses the Road style instead.

Zoom Level

The Zoom Level property 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 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.

Center Latitude and Center Longitude

The Center Laitude and Center Longitude properties specify 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 latitude and 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 Latitude and Center Longitude properties.

Use Marker Clusters

The Use Marker Clusters checkbox controls whether markers that are near each other are grouped together when the map is zoomed out far enough that the markers would be very close together. The default value is unchecked.

Using marker clusters may help to declutter a map that has a lot of markers. On the the other hand, it obscures the actual location of a marker until the map is zoomed in enough that the marker separates from its cluster.

Item List

The Item List 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.

Second Site creates maps that are very similar to GedSite's maps. 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, then use the Map Editor > Edit Map... command in the Edit Map Item window to open the Map Editor. GedSite 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.

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

• The hand tool moves the map and clicking it will turn off any of the other three.
• The balloon tool creates a marker
• The polygon tool creates a multi-sided shape
• The line tool creates a multi-segment line

Markers are created with a single click. To edit the name of a marker, and other properties, double-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., double-click on the item or double-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 up/down icon and while holding the mouse button down, drag the item to the position you want then release the mouse button.

To edit a line or polygon, click it to select it, then drag the points. While editing the shape, click on a point to delete it. You can click on the "ghost points" to add a point between two existing points. The ghost points lie halfway between the existing points.

To add a vertex to either end of a line, move 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 "+" 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 delete an item, double-click the item in the item list to open the Edit MapItem panel, then click the Delete link in that panel.

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, GedSite 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.

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 may want to build the site at least once and adjust the zoom and other map parameters based on the end result rather than rely solely on how the map looks in the Map Editor.

Map Events Properties

Each Map Events item includes the following properties.

Title

The Title property identifies the Map Events Item in the Map Events list. The Map Events Title has no other purpose.

Enabled

See Enabled in the Common Properties section of the User Items help page.

Icon

The Icon pull-down menu determines the icon used for markers added by this Map Events item.

Choose "Standard" to use the default icon determined by the mapping service. Choose "Numbered" to use icons that are numbered according to the date of the earliest event at the marker location. 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.

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.

Filters

For each Map Events item, you may specify a Person Filter to choose whose events are included, and an Event Filter to chose which events for those people are included. See the Filters section for more information about filters.

Marker Sequence

If the Map User Item has an Item List, the markers added by this Map Events item will be sorted according to the value of this property.

The default item sequence is "By Earliest Date": the markers are sorted by the date of the earliest dated event that occurred at the place.

You may also sort "By Place Name": the markers are sorted by the name of the place. If two (or more) places share the same latitude and longitude coordinates, the name that appears in the list is taken from the first event that GedSite finds when it searches for events.

If the Map User Item has multiple Map Events items, the markers for Map Events item #1 will appear before the markers for Map Events item #2, etc.

Show Coordinates

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

Show Place Note

If Show Place Note is checked, the information box for the location will include the Note field from the Place record, if any. The default value is unchecked.

Add Line

You can connect the events defined by a Map Events entry using the Add Line checkbox. When checked, GedSite will add a multi-segment line 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 GedSite, such as the initial center point of the map, you enter coordinates using decimal degrees notation. In decimal degrees 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 degrees notation is used by most GPS devices and by all the major online mapping services.

Consult the help system for your genealogy program to determine where to enter the latitude and longitude, and what format to use.

Determining Coordinates

If you have a handheld GPS device, you can find the coordinates of any place you can visit, and you probably already 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. Some services have better maps than others for certain areas.

• Google Maps – Easy to use to find the location of interest, but requires a little trick to get the coordinates. (See the Determining Coordinates using Google instructions below.)
• iTouchMap

The GedSite 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 Google Maps site.

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 "What's here?" from the pop-up menu.
4. A marker will be added to the map and an information panel will appear at the bottom of the window.
5. Click the coordinates which are shown as a link at the bottom of the information panel. When you click the coordinates, they will be transferred to the search box near the top of the window. Copy the coordinates from the search box.

Notes

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