TripGeo - Map Your Trip     Home   City Guides   Hotel Search   Mapping Projects   Contact  
If a sign-in error occurs please click the 'clear' link then retry.

Trail Charts API - map a collection of trails from a spreadsheet source

Trail Charts is a mapping API which can be used on your website to display a large number of separate KML feeds (trails) on a map.

A speadsheet is the main data source, containing one row per trail. Any number of additional columns (fields) can be contained in the speadsheet.

Template functions allow you to easily customize how these fields are displayed within the map.

Two maps are used, the first map displays the overall area and the second map displays the currently selected trail.

Menus and submenus can filter your trails by category or by date.


Terms of Use

The Trail Chart API can be used for any commercial or non-commercial project provided that:

(1) The copyright notice in the javacript code (see main.js) is included.

(2) A link to www.tripgeo.com or www.tripgeo.com/TrailCharts.aspx is displayed somewhere on the web page where the Trail Chart is displayed.


Please contact us at tripgeo @ gmail.com if you have an example Trail Chart that you would like featured here.



Getting Started

Prepare the Data File

Your main data file is a comma-separated or tab-separated text file containing your trail data (one row per trail).

The data file can be created and edited with a program such as Microsoft Excel or a web service such as Google Spreadsheets.

A Google Spreadsheet can be saved by adding &output=txt to the spreadsheet URL, viewing in the browser and then saving the page to file.

The example Trail Chart displays a feed located at http://www.tripgeo.com/js/trailchart/feed/hikemaster.txt.


Save the data as tab-delimited text (also refered to as tab separated values, TSV)

The data file should contain columns for name, lat, lng and either kml or kmz.

Additional columns can be created. Data from these columns can be incorporated into the Trail Chart using templates (see the API Reference).

The column heading name can be used as a variable within the template for the info panel, info window, list item, marker or photo.

Variables are case sensitive, setting them all to lower-case with no punctuation is recommended.


Screenshot of an Example Spreadsheet (click for more detail)


Create an HTML page

The next step is to create a web page to display the Trail Chart.

The default page type is HTML. Others types of web page can be used (e.g. PHP or ASP) depending upon your development environment.

A good way to get started is to copy the example files, then change the settings for your own data. The example html page is named map.htm

Download and extract the zipped archive below, then add these files to you website. It is recommended to keep the files in a folder separate from your main project files, e.g. use a folder named trailchart.


Customize the Trail Chart

Once the example Trail Chart has been downloaded and loads successfully into your browser you can start editing the settings.

First replace the hikes.txt feed with your own feed. The feedUrl parameter sets the location of this feed. Note that the file must be located in the same domain as your web page.

The dimensions and placement of all the panels in map.htm can be changed as required.

The HTML which controls the menu mode (date or category) can be removed or relocated.

See the API reference for a full list of parameters which can be changed.


Using the Templates

Templates are options which allow you to change the format of sections of text without having to modify the main Trail Chart code.

A template is simply a section of HTML code with variable names enclosed in braces { }.

Variable names are taken from the first row (column headings) of the feed data. All variables are treated as strings.

Change the template settings in the example Trail Chart to see how templates work.

Templates are defined using the following parameters: markerTemplate, listTemplate, infoTemplate, infoWindowTemplate, photoTemplate


Javascript Screenshot
var l_listTemplate =
"<img src='mk/m{difficulty}.png' /> <b>{title}</b>" +
"<div style='padding-top:4px; padding-bottom:4px; color:gray'>" +
"{day} {month} {year}</div>"
;
var l_infoTemplate =
"<h2>{title}</h2>" +
"Difficulty: {difficulty2}<br/>" +
"Elevation: {elevation}<br/>" +
"Season: {season}<br/>" +
"Date: {datetext}<br/>" +
"<a target='_blank' href='http://maps.google.com/maps?daddr={lat},{lng}+({title})'>Get Directions</a><br/>
"<strong>Description</strong> | <a target='_blank' href='{photo album url}'>Photo Journal</a> |<br/>" +
"{description}"
;
var l_infoWindowTemplate =
"<img src='mk/m{difficulty}.png' /> <b>{title}</b><br/>{datetext}";
var l_photoTemplate =
"<table><tr valign='top'><td style='width:160px'>" +
"<a target='_blank' href='{photo album url}'><img src='{photo url}' style='max-width:305px;max-height:205px' />" +
"</td><td>" +
"<a target='_blank' href='{photo album url}'> Photo Journal </a><br/>" +
"<a target='_blank' href='{topography}'> Topo Maps PDF </a><br/>" +
"<a target='_blank' href='{kmz}'>KML/KMZ</a><br/></br>" +
"</td></tr></table>"
;

Handling of Date Values

The date field is a special case, when a date field is defined, three other fields are created: day, month and year which can be used within templates.

The values used for dates must be in the format YYYYMMDD, e.g. 20120229.


Examples

Example Trail Chart 1 - California and Yosemite Wilderness Hikes Map

View the full collection of hikes at MrHollister.com Hikes & Adventures - Yosemite and California Wilderness Hikes.

trailchart.zip   source code



California and Yosemite Wilderness Hikes Map (compressed javascript code)

trailchart_compressed.zip   source code (compressed)



Example Trail Chart 2 - London 2012 Torch Relay Route Map

London 2012 Torch Relay Route Map

torch.zip   source code



Example Trail Chart Script

<script type='text/javascript'>

function loadPage()
{
var l_markerTemplate = "mk/m{difficulty}.png";
  
var l_listTemplate =
   "<img src='mk/m{difficulty}.png' /> <b>{title}</b>" +
   "<div style='padding-top:4px; padding-bottom:4px; color:gray'>" +
   "{day} {month} {year}</div>";
  
var l_infoTemplate =
   "<h2>{title}&/h2>" +
   "Difficulty: {difficulty2}<br/>" +
   "Elevation: {elevation}<br/>" +
   "Season: {season}<br/>" +
   "Date: {datetext}<br/>" +
   "<a target='_blank' href='http://maps.google.com/maps?daddr={lat},{lng}+({title})'>Get Directions</a><br/>" +
   "<br/>" +
   "{description}" +
   "<br/><br/>" +
   "<a target='_blank' href='{photo album url}'>Photo Album</a><br/><br/>";



var l_infoWindowTemplate =
   "<img src='mk/m{difficulty}.png' /> <b>{title}</b><br/>{datetext}";
  
   var l_photoTemplate =
   "<table><tr valign='top'><td style='width:160px'>" +
   "<img src='{photo url}' style='max-width:150px;max-height:150px' />" +
   "</td><td>" +
   "<a target='_blank' href='{photo album url}'>more photos</a><br/><br/>" +
   "<a target='_blank' href='{topography}'>topography</a>" +
   "</td></tr></table>";

var l_trailOptions =
{
   feedUrl: "feed/hikemaster.txt",
   feedType: "tsv",
   feedQuotes: false,
   mainMapType: 3,
   trailMapType: 2,
   maxZoom: 8
   markerTemplate: l_markerTemplate,
   listTemplate: l_listTemplate,
   infoTemplate: l_infoTemplate,
   infoWindowTemplate: l_infoWindowTemplate,
   photoTemplate: l_photoTemplate,
   fieldTitle: "title",
   fieldLatitude: "lat",
   fieldLongitude: "lng",
   fieldCategory: "category",
   fieldSubcategory: "subcategory",
   fieldDate: "date",
   fieldKML: "kmz",
   sortField: "difficulty",
   sortReverse: false
};

var trailchart = new TC1(l_trailOptions);
}

window.onload = loadPage;
</script>

API Reference

TC1

The main Trail Chart class

Constructor

TC1(opts? : TC1Options)

Methods

Methods Return Value Description
- - -

TC1Options

A set of parameters used when creating a new Trail Chart

Properties Type Description
feedUrl string URL of the tab-delimited text data feed
feedType string either "tsv" (tab-separated values) or "csv" (comma-separated values). "tsv" is the default used if this parameter is not supplied.
feedQuotes bool if true, single quotes can be used to delimit fields within the feed and double quotes are converted into single quotes. if false, no text conversion of the feed occurs.
maxZoom int The maximum zoom level applied to the main map when a menu item is clicked
mainMapType int 0=Road 1=Satellite 2=Hybrid 3=Terrain
trailMapType int 0=Road 1=Satellite 2=Hybrid 3=Terrain
markerTemplate string The template used to generate the url of a marker icon image
infoTemplate string The template used to generate the information panel HTML displayed in the sidebar when a trail is selected.
infoWindowTemplate string The template used to generate the HTML displayed inside the info window (bubble) displayed on the map when a trail is selected.
listTemplate string The template used to generate the list item HTML displayed for a trail within the sidebar trail list.
photoTemplate string The template used to generate the HTML displayed in the photo panel (beneath the trail map).
fieldLatitude string The heading name of the feed column which contains the latitude values, default = "lat".
fieldLongitude string The heading name of the feed column which contains the longitude values, default = "lng".
fieldTitle string The heading name of the feed column which contains the title values, default = "title".
fieldCategory string The heading name of the feed column which contains the category values, default = "category".
fieldSubcategory string The heading name of the feed column which contains the subcategory values, default = "subcategory".
fieldDate string The heading name of the feed column which contains the date values, default = "date".
fieldKML string The heading name of the feed column which contains the KML or KMZ url values, default = "kml".
menuMode string Specifies how the menu if initially organised. either "category" or "date".
menuDateMode string Specifies how the menu is organised if the menuMode is set to "date". Can be "months", days" or "monthdays".
sortField string Specifies the field used for sorting the trail list. The default sort field is 'title'.

* Applies when the 'category' menu mode is selected. When date menu mode is selected, trails will be sorted by date descending.
sortReverse bool If true, the trail list will be sorted in reverse order when the 'category' menu mode is selected. The default value is false.
menuSortReverse bool If true, the menu items are displayed in reverse order (e.g. most recent dates first).
menuPrevNext bool if true, previous and next links are displayed on the right sub-menu bar when a marker is selected.
infoWindowHeight int If non-zero specifies the height in pixels of the info window.

Global Functions

Function Name Return Value Description
applyMenu(menumode, ?datemode) none Creates a new menu system specifiied by the menumode parameter (either "date" or "category"). If "date" is the menumode then a datemode parameter can be used, one of "months", "days" or "monthdays".

In the example map there are links above the trail chart which demonstrate the use of this function.
applySort(sortField, ?sortReverse) none Sorts the trail list by the specified sort field (e.g. "title", "date")

sortReverse will display the list in descending order if true or ascending order if false.


Development by   Map Channels