In this tutorial, the first steps for using GeoTemCo with your data are explained. We suppose the common case of one geospatial dimension to be displayed in a map widget, one temporal dimension to be displayed in a time widget and one table widget that shows the data items' details. The accepted data standards and the formats to be fulfilled for displaying datasets with GeoTemCo are:
KMLThe following 5 steps need to be done to display datasets in GeoTemCo's widgets are:
1. Include FilesOther selected topics for setting up and using GeoTemCo are:
Map ConfigurationPlease, also inspect the written source code snippets in the Live Examples' section for detailed overview.
One data format which can be displayed with GeoTemCo is KML. A detailed overview is given in the KML Reference. The general structure of KML is:
The Folder-Tag holds a list of data items of a dataset. KML fits properly with the common case of 3 widgets (map, time, table). The following information for a single data item can be captured inside a KML's Placemark-Tag:... ... ... ...
Note: If a data's entry can contain special characters, e.g. its description, additionally frame it with the CDATA tag:item name item description place namelongitude,latitude date
<![CDATA[item description]]>
Another accepted format in JSON. Compared to KML its structure is not standardized, but it is more compact. Therefore, the size of a dataset is smaller, which makes significant performance differences especially for large datasets. The global structure of a dataset is an array with a JSON entry for each data item.
[ ... dataItem, dataItem, dataItem, ... ]Each dataItem contains the given geospatial and temporal information. Furthermore, there are several possibilities for a data items' description. A single data item entry looks like:
{ "id": someId, "weight": someWeight, "name": someName, "description": someDescription, "lon": someLongitude, "lat": someLatitude, "place": somePlaceName, "time": someDate, "tableContent": someValuesList }The values of the attributes are slightly different compared to KML:
GeoTemCo uses the JavaScript libraries OpenLayers for the map widget and SIMILE Timeplot for the time widget. Both sources, other required JavaScript libraries and the GeoTemCo JavaScript files are combined and minified in one GeoTemCo source file. In the Source Code section, you can download the bundle version which you extract into your client folder. Then, include the GeoTemCo sources into the head environment of the HTML-page with:
<head> ... <link rel="stylesheet" href="geotemco_directory/css/geotemco.css" type="text/css"/> <script src="geotemco_directory/geotemco-min.js"/> ... </head>
Dependent on the given data source you need to place a specific number of HTML containers for initializing different widgets to show the data's metadata. For the common case, 3 divs for 3 widgets (map, time and table) are required:
Each widget needs 2 things for its initialization: its container div and a corresponding wrapper. A wrapper can be seen as an interface, which manages interaction between the different widgets. Additionally, you can give a JSON set of options for each widget.
var mapDiv = document.getElementById("someMapDivName"); var map = new WidgetWrapper(); var mapWidget = new MapWidget(map,mapDiv,options); var timeDiv = document.getElementById("someTimeDivName"); var time = new WidgetWrapper(); var timeWidget = new TimeWidget(time,timeDiv,options); var tableDiv = document.getElementById("someTableDivName"); var table = new WidgetWrapper(); var tableWidget = new TableWidget(table,tableDiv,options);An overview of options you can set for map, time and table widget are given in: Map Configuration, Time Configuration and Table Configuration.
The needed function call depends on your data format choice. If you need to retrieve the files you can use the following request to get the XML tree for KML's via:
var kmlFile = GeoTemConfig.getKml('someKmlUrl');For JSON files use:
var jsonFile = GeoTemConfig.getJson('someJsonUrl');Having the files, you can load the data with:
var kmlData = GeoTemConfig.loadKml(kmlFile);For JSON files use:
var jsonData = GeoTemConfig.loadJson(jsonFile);
Each GeoTemCo widget always expects an array of Dataset objects for displaying. Since the aggregation procedures for map and time widget takes most of the initialization time, we waived on implementing some sort of "addDataset"- or "removeDataset"-functions. A simple way of initializing GeoTemCo with a Dataset array is:
// empty array for datasets var datasets = []; // a series of loading datasets (in this case json files) ... var jsonFile = GeoTemConfig.getJson('someJsonUrl'); var jsonData = GeoTemConfig.loadJson(jsonFile); var dataset = new Dataset(jsonData,'someDatasetLabel'); datasets.push(dataset); ...The labels are used for the table's tabs. Finally, we load the data into the widgets with:
map.display(datasets); time.display(datasets); table.display(datasets);After these 5 steps, the data should be shown in all widgets.
Below, you can find the standard configuration of the map widget:
mapWidth : false, // false or desired width css definition for the map mapHeight : '580px', // false or desired height css definition for the map mapTitle : 'GeoTemCo Map View', // title will be shown in map header mapIndex : 0, // index = position in location array; for multiple locations the 2nd map refers to index 1 alternativeMap : false, // alternative map definition for a web mapping service or 'false' for no alternative map /* an example: { name: 'someMapName', url: '/geoserver/wms', layer: 'namespace:layerName' } */ googleMaps : false, // enable/disable Google maps (actually, no Google Maps API key is required) bingMaps : false, // enable/disable Bing maps (you need to set the Bing Maps API key below) bingApiKey : 'none', // bing maps api key, see informations at http://bingmapsportal.com/ osmMaps : true, // enable/disable OSM maps baseLayer : 'Open Street Map', // initial layer to show (e.g. 'Google Streets') resetMap : true, // show/hide map reset button countrySelect : true, // show/hide map country selection control button polygonSelect : true, // show/hide map polygon selection control button circleSelect : true, // show/hide map circle selection control button squareSelect : true, // show/hide map square selection control button multiSelection : true, // true, if multiple polygons or multiple circles should be selectable popups : true, // enabled popups will show popup windows for circles on the map olNavigation : false, // show/hide OpenLayers navigation panel olLayerSwitcher : false, // show/hide OpenLayers layer switcher olMapOverview : false, // show/hide OpenLayers map overview olKeyboardDefaults : true, // (de)activate Openlayers keyboard defaults olScaleLine : false, // (de)activate Openlayers keyboard defaults geoLocation : true, // show/hide GeoLocation feature boundaries : { minLon : -29, minLat : 35, maxLon : 44, maxLat : 67 }, // initial map boundaries or 'false' for no boundaries mapCanvasFrom : '#9db9d8', // map widget background gradient color top mapCanvasTo : '#5783b5', // map widget background gradient color bottom labelGrid : true, // show label grid on hover maxPlaceLabels : 6, // Integer value for fixed number of place labels: 0 --> unlimited, 1 --> 1 label (won't be shown in popup, 2 --> is not possible because of others & all labels --> 3 labels, [3,...,N] --> [3,...,N] place labels) selectDefault : true, // true, if strongest label should be selected as default maxLabelIncrease : 2, // maximum increase (in em) for the font size of a label labelHover : false, // true, to update on label hover ieHighlightLabel : "color: COLOR1; background-color: COLOR0; filter:'progid:DXImageTransform.Microsoft.Alpha(Opacity=80)';-ms-filter:'progid:DXImageTransform.Microsoft.Alpha(Opacity=80)';", // css code for a highlighted place label in IE highlightLabel : "color: COLOR0; text-shadow: 0 0 0.4em black, 0 0 0.4em black, 0 0 0.4em black, 0 0 0.4em COLOR0;", // css code for a highlighted place label ieSelectedLabel : "color: COLOR1; font-weight: bold;", // css code for a selected place label in IE selectedLabel : "color: COLOR1; font-weight: bold;", // css code for a selected place label ieUnselectedLabel : "color: COLOR1; font-weight: normal;", // css code for an unselected place label in IE unselectedLabel : "color: COLOR1; font-weight: normal;", // css code for an unselected place label ieHoveredLabel : "color: COLOR1; font-weight: bold;", // css code for a hovered place label in IE hoveredLabel : "color: COLOR1; font-weight: bold;", // css code for a hovered place label circleGap : 0, // gap between the circles on the map (>=0) minimumRadius : 4, // minimum radius of a circle with mimimal weight (>0) circleOutline : true, // true if circles should have a default outline circleTransparency : true, // transparency of the circles minTransparency : 0.4, // maximum transparency of a circle maxTransparency : 0.8, // minimum transparency of a circle binning : "generic", // binning algorithm for the map, possible values are: 'generic', 'square', 'hexagonal', 'triangular' or false for 'no binning' noBinningRadii : "dynamic", // for 'no binning': 'static' for only minimum radii, 'dynamic' for increasing radii for increasing weights circlePackings : true, // if circles of multiple result sets should be displayed in circle packs, if a binning is performed binCount : 10, // number of bins for x and y dimension for lowest zoom level showDescriptions : true, // true to show descriptions of data items (must be provided by kml/json), false if not mapSelection : true, // show/hide select map dropdown binningSelection : false, // show/hide binning algorithms dropdown mapSelectionTools : true, // show/hide map selector tools dataInformation : true, // show/hide data information overlayVisibility : false, // initial visibility of additional overlays proxyHost : '' //required for selectCountry feature, if the requested GeoServer and GeoTemCo are NOT on the same serverTo overwrite, e.g. the values for 'mapTitle' and 'googleMaps', you just need to initialize the map widget with:
var mapWidget = new MapWidget(map,mapDiv,{ mapTitle: 'Some Map Title', googleMaps: true });
Below, you can find the standard configuration of the time widget:
timeTitle : 'GeoTemCo Time View', // title will be shown in timeplot header timeIndex : 0, // index = position in date array; for multiple dates the 2nd timeplot refers to index 1 timeWidth : false, // false or desired width css definition for the timeplot timeHeight : '100px', // false or desired height css definition for the timeplot defaultMinDate : new Date(2012, 0, 1), // required, when empty timelines are possible defaultMaxDate : new Date(), // required, when empty timelines are possible timeCanvasFrom : '#EEE', // time widget background gradient color top timeCanvasTo : '#EEE', // time widget background gradient color bottom rangeBoxColor : "white", // fill color for time range box rangeBorder : "1px solid #de7708", // border of frames dataInformation : true, // show/hide data information rangeAnimation : true, // show/hide animation buttons scaleSelection : true, // show/hide scale selection buttons linearScale : true, // true for linear value scaling, false for logarithmic unitSelection : true, // show/hide time unit selection dropdown timeUnit : -1 // minimum temporal unit (SimileAjax.DateTime or -1 if none) of the dataTo overwrite, e.g. the values for 'timeTitle' and 'timeUnit', you just need to initialize the time widget with:
var timeWidget = new TimeWidget(time,timeDiv,{ timeTitle: 'Some Time Title', timeUnit: SimileAjax.DateTime.YEAR });
Below, you can find the standard configuration of the table widget:
tableWidth : false, // false or desired width css definition for the table tableHeight : false, // false or desired height css definition for the table validResultsPerPage : [10, 20, 50, 100], // valid number of elements per page initialResultsPerPage : 10, // initial number of elements per page tableSorting : true, // true, if sorting of columns should be possible tableContentOffset : 250, // maximum display number of characters in a table cell tableSelectPage : true, // selection of complete table pages tableSelectAll : false, // selection of complete tables tableShowSelected : true, // show selected objects only option unselectedCellColor : '#EEE' // color for an unselected row/tabTo overwrite, e.g. the values for 'tableSorting' and 'unselectedCellColor', you just need to initialize the table widget with:
var tableWidget = new TableWidget(table,tableDiv,{ tableSorting: false, unselectedCellColor: 'white' });
GeoTemCo accepts dates in the following formats in XML time (see XML Schema Part 2: Datatypes Second Edition):
For places, a unique place name is shown at all zoom levels, but we are also able to separate different levels of detail. We accept 4 different level place names describing a data items' location which are shown at proper map resolutions:
USA/New York/New York City/Liberty IslandFor missing levels, the coarser level name is shown. In such a case, leave unknown level names empty like:
USA//New York City/Liberty Island
For data with multiple geospatial and/or temporal dimensions, you need to perform some modifications. For a better understanding, an example which requires 2 map and 2 time widgets. Therefore, suppose a set of excavations artifacts with:
{ ... "lon": someLongitude, "lat": someLatitude, "place": somePlaceName, ... }with a location array that holds multiple places (in this case 2 places):
{ ... "location": [ { "lon": someLongitude1, "lat": someLatitude1, "place": somePlaceName1 }, { "lon": someLongitude2, "lat": someLatitude2, "place": somePlaceName2 } ], ... }For multiple temporal dimensions you simply need to replace the date value with an array of dates:
{ ... "time": [ someDate1, someDate2 ], ... }Each dimension requires its own div and wrapper. For the example of 2 geospatial and 2 temporal dimensions, we instantiate 2 MapWidget objects (map1, map2) and 2 TimeWidget objects (time1, time2) with:
var mapDiv1 = document.getElementById("someMapDivName1"); var map1 = new WidgetWrapper(); var mapWidget1 = new MapWidget(map1,mapDiv1,{ mapIndex: 0 }); var mapDiv2 = document.getElementById("someMapDivName2"); var map2 = new WidgetWrapper(); var mapWidget2 = new MapWidget(map2,mapDiv2,{ mapIndex: 1 }); var timeDiv1 = document.getElementById("someTimeDivName1"); var time1 = new WidgetWrapper(); var timeWidget1 = new TimeWidget(time1,timeDiv1,{ timeIndex: 0 }); var timeDiv2 = document.getElementById("someTimeDivName2"); var time2 = new WidgetWrapper(); var timeWidget2 = new TimeWidget(time2,timeDiv2,{ timeIndex: 1 });For the widgets showing the second dimensions (map2, time2), you need to set the option 'mapIndex' to the dedicated array position 1. The standard mapIndex-value is 0. These are all changes for displaying multiple geospatial or temporal dimensions.
GeoTemCo uses an own mechanism for subscribing functions to be called when specific topics are published. The most important topics are:
var object = this; Publisher.Subscribe('filterData',object,function(data){ // any code here, e.g.: // object.filter(data); });The "object" variable is the object which subscribes for the topic. "data" contains all data items within the 'filter' event. You are also able to publish such an event with:
Publisher.Publish('filterData',data,object);Now, the "object" value is used to avoid calling subscribed functions from "object". If the subscribed function from "object" still should be called you can publish like:
Publisher.Publish('filterData',data,null);You can use this mechanism to publish and subscribe objects for any topic you like.