olwidget.js is a standalone javascript library to make editing and displaying geometries and information on OpenLayers maps easier. The library defines two main types of objects – map types and vector layer types. Maps may contain one or more vector layer, which may be editable, or may contain features which produce popup bubbles when clicked.
Copy or link the olwidget media directory (which contains js/, css/, and img/ directories into your website’s path. The three directories should share a parent.
olwidget supports multiple geometry types, any number of maps per page, multiple map providers, and much more (see options below). A simple example of how to use it:
<html>
<head>
<script type='text/javascript' src='http://openlayers.org/api/2.9/OpenLayers.js'></script>
<script type='text/javascript' src='http://openstreetmap.org/openlayers/OpenStreetMap.js'></script>
<script type='text/javascript' src='olwidget/js/olwidget.js'></script>
<link rel='stylesheet' href='olwidget/css/olwidget.css' />
</head>
<body>
<!-- a map with an editable overlay -->
<textarea id='my_point'>SRID=4326;POINT(0 0)</textarea>
<script type='text/javascript'>
new olwidget.EditableMap('my_point', {name: 'My Point'});
</script>
<!-- a map displaying an info popup over a geometry -->
<div id='map'></div>
<script type='text/javascript'>
new olwidget.InfoMap('map', [
['SRID=4326;POINT(0 0)', "<p>Here at the zero point!</p>"]
]);
</script>
</body>
</html>
See Examples for several examples of olwidget in action.
olwidget.Map is the primary map type used by olwidget; the other types are just convenience wrappers of this type. Constructor:
new olwidget.Map(mapDivID, vectorLayers, options)
<div id="map"></div>
<script type='text/javascript'>
new olwidget.Map("map", [
new olwidget.InfoLayer([["POINT (0 0)", "the origin"]], {
name: "Origin"
}),
new olwidget.InfoLayer([["POINT (1 0)", "one degree off"]], {
name: "A little off"
})
], {
layers: ['osm.mapnik', 'osm.osmarender']
});
</script>
olwidget.InfoMap is a convenience type for defining a map with one info layer.
Constructor:
new olwidget.InfoMap(mapDivId, info, options);
The following produce identical maps:
new olwidget.InfoMap(mapDivId, info, options);
new olwidget.Map(mapDivId, [new olwidget.InfoLayer(info)], options);
olwidget.EditableMap is a convenience type for defining a map with one editable layer.
Constructor:
new olwidget.EditableMap(textareaId, options);
The following produce identical maps, with the exception that the olwidget.EditableMap creates a div to contain the map dynamically, where olwidget.Map does not.
new olwidget.EditableMap(textareaId, options);
new olwidget.Map(mapDivId, [new olwidget.EditableLayer(textareaId)], options);
olwidget.EditableLayer is a layer type which reads and writes WKT geometry data to a textarea. Constructor:
new olwidget.EditableLayer(textareaId, options);
Create a map that contains two editable layers:
<div id='map'></div>
<textarea id='geom1'>POINT (0 0)</textarea>
<textarea id='geom2'>POINT (1 1)</textarea>
<script type='text/javascript'>
new olwidget.Map('map', [
new olwidget.EditableLayer('geom1', {'name': "The origin"}),
new olwidget.EditableLayer('geom2', {'name': "A bit off"})
], { 'overlayStyle': { 'fillColor': "#ff0000" }});
</script>
olwidget.InfoLayer is a layer type which displays geometries with clickable popups containing HTML. Constructor:
new olwidget.InfoLayer(info, options);
An array of [geom, html] pairs, where geom is a WKT geometry, and html is a string containing HTML to display in the popup. html can also be an object containing style information for the particular geometry, with the following format:
{
'html': "An html string"
'style': {
// style properties for this geometry
}
}
The following is an example olwidget.Map with olwidget.InfoLayer instances using geometry-specific styles, layer-specific styles, and map styles together. See this example for a full example of style inheritance:
<div id='map'></div>
<script type='text/javascript'>
new olwidget.Map('map',
[new InfoLayer([["POINT (0 0)", { html: "The origin",
style: {
'fillColor': "#00FF00"
}],
["POINT (0 1)", { html: "A degree off",
style: {
'fillColor': "#FF0000"
}]],
{ // Layer-wide options
'overlayStyle': {
'strokeColor': "#0000FF"
}
}),
], { // Map-wide options
'overlayStyle': {
'strokeWidth': 6
}
})
</script>
Maps are both important user interface elements, and powerful persuasive data displays. Consequently, it is necessary to support a high degree of customization around the appearance of a map. OLWidget does this primarily through the use of OpenLayers’ style framework. All of OLWidget’s types accept an optional options dict which controls the appearance of the map and layers.
Layers inherit their styles from both their default parameters, and from those specified for a map:
default options < map options < layer options
This allows the map to hold defaults for all layers, but let the layers override them. See this example for a full example of style inheritance with multi-layer maps.
The following is a list of all available options. Some are specific to map display, and others specific to layer display.
A list of map base layers to include. Choices include 'osm.mapnik', 'osm.osmarender', 'google.streets', 'google.physical', 'google.satellite', 'google.hybrid', 've.road', 've.shaded', 've.aerial', 've.hybrid', 'wms.map', 'wms.nasa', 'yahoo.map', and 'cloudmade.<num>' (where <num> is the number for a cloudmade style). A blank map can be obtained using 'wms.blank'. Additional providers or options can be manually added using the normal OpenLayers apis (see this provider example).
You must also include whatever javascript sources are needed to use these (e.g. maps.google.com or openstreetmap.org apis). For CloudMade maps, use the included cloudmade.js file, and append the API key as the hash portion of the URL, for example:
<!-- API key for http://olwidget.org -->
<script src="js/cloudmade.js#06c005818e31487cb270b0bdfc71e115" type="text/javascript"></script>
See the other providers for a full example of all built-in layer providers.
An object containing options for the OpenLayers Map constructor. Properties may include:
Any additional parameters available to the OpenLayers.Map.Constructor may be included, and will be passed directly.
The direction from the clicked geometry that a popup will extend. This may be one of:
The way HTML from clustered points is handled:
A couple of internal olwidget types might be useful outside olwidget as well.
olwidget defines its own Popup type, which it uses for display of popups in InfoLayer instances. The popup differs from default OpenLayers popup types in a few important ways: first, it is styled primarily using CSS rather than hard-coded javascript. Second, it will paginate data if it is passed an array as the contentHTML parameter. Third, it can be placed outside the map’s viewport as well as inside it. The popup’s CSS class hierarchy is as follows:
<div> <!-- container div for popup -->
<div class='olPopupContent'> <!-- the main content frame -->
<div class='olwidgetPopupContent'>
<div class='olwidgetPopupCloseBox'>
<!-- the close box -->
</div>
<div class='olwidgetPopupPage'>
<!-- the message in the popup -->
</div>
<!-- paginator shown only if contentHTML is an array -->
<div class='olwidgetPopupPagination'>
<div class='olwidgetPaginationPrevious'></div>
<div class='olwidgetPaginationCount'></div>
<div class='olwidgetPaginationNext'></div>
</div>
<div style='clear: both;'></div>
</div>
<!-- the stem class may be one of:
olwidgetPopupStemBR (bottom right),
olwidgetPopupStemBL (bottom left),
olwidgetPopupStemTR (top right),
olwidgetPopupStemTL (top left) -->
<div class='olwidgetPopupStemBR'></div>
</div>
</div>
olwidget.DeleteVertexControl is a simple control which deletes vertices when they are clicked. It may be useful outside of olwidget.
olwidget uses the projections given in mapOptions to determine the input and output of WKT data. By default, it expects incoming WKT data to use "EPSG:4326" (familiar latitudes and longitudes), which is transformed internally to the map projection (by default, "EPSG:900913", the projection used by OpenStreetMaps, Google, and others). Currently, olwidget ignores the SRID present in any initial WKT data, and uses the projection specified in mapOptions.displayProjection to read the data.
To change the projection used for WKT, define the mapOptions.displayProjection. For example, the following will use EPSG:900913 for all WKT data in addition to map display:
new olwidget.EditableMap('textareaId', {
mapOptions: {
projection: "EPSG:900913",
displayProjection: "EPSG:900913"
}
});