#NinjaArrows.js ##for Google Maps and OpenLayers NinjaArrows is a Google Maps/OpenLayers extension that displays arrows at the map's eged showing positions and the number of out-of-bounds markers. By clicking on an arrow the map will extend its bounds to show out-of-bounds markers in a special direction or change its viewport to display only these markers. NinjaArrows.js also allows you to apply a custom style for your arrows including fill color, stroke color and text color and offsets
- Google Maps
- OpenLayers
- Offsets
- Dynamic Colors (Google Maps v1.2+ , OpenLayers v1.1+)
This project was created at ilogs mobile software GmbH. Please also visit my blog NinjaArrows to receive the lastest news.
##Usage
###Google Maps
Creating a new instance
To use NinjaArrows and its features simply create a new NinjaArrows instance by passing a map to the constructor.
var ninjaArrows = new NinjaArrows(map);You can also pass an existing array of Markers to the constructor:
var markers = [];
// add markers ...
var ninjaArrows = new NinjaArrows(map, markers);You can also initialize NinjaArrows with several options, i.e. style, offsets etc.
var customStyle = {
fillColor: "yellow",
strokeColor: "orange",
strokeWidth: 2,
textColor: "black"
};
var ninjaArrows = new NinjaArrows(map, markers, { style: customStyle } );Adding and removing markers
To add a new marker simply call addMarker():
ninjaArrows.addMarker(marker);The same applies to removing markers. Just call removeMarker() to remove the given marker from NinjaArrows.
ninjaArrows.removeMarker(marker);To clear all markers, call clearMarkers():
ninjaArrows.clearMarkers();Options
You can apply several options to the arrows: style, edgeOffset, borderOffset and jumpTo-Flag
style
Pass a style object to the NinjaArrows constructor or use setStyle(style) to apply a custom style. A style object defines these attributes: (If an attribute is not specified in the style object, the default property is taken.)
{
fillColor: string,
strokeColor: string,
strokeWidth: number,
textColor: string
}Dynamic Colors (v1.2+)
{
fillColor: string,
strokeColor: string,
strokeWidth: number,
textColor: string,
type: string,
colorStops: [],
resolution: number,
maximum: number
}The new style object includes type, colorStops, resolution and maximum.
type
If type property is set to gradient a gradient will be generated based on the colorStops array and the resolution. Default is default.
colorStops
The colorStops array specifies the colors used for the spectrum to be generated. A color must be a hexadecimal string.
resolution
resolution specifies the gradient's resolution.
maximum
maximum specifies the maximum an arrow's count muast have to get the last color in the spectrum.
Example:
var style = {
type: "gradient",
colorStops: ["#00CC00", "#FFFF00", "#FF0000"],
resolution: 100,
maximum 50
};When applying the style above a gradient will be generated containing 100 colors ranging from green to yellow and red. A marker with count 1 will be green, all markers with count above 50 (the maximum) will be red and the markers between will get the matching color from the gradient.
edgeOffset
This is the minimum distance in pixel between arrow at top/bottom and left/right. (Arrows won't overlap in corners). Use setEdgeOffset(offset) to change the offset. Default is 75px.
borderOffset
This is the offset from the map's border to the arrows. Use setBorderOffset(offset) to change the offset in pixel.
{
top: 0,
right: 0,
bottom: 0,
left: 70
};jumpTo
This flag specifies whether the map's bounds should extend to contain out-of-bounds markers or jump to out-of-bounds markers. Use setJumpTo(flag)
zoomOnClick
Flag that specifies default behaviour of an arrow icon click. Use set zoomOnClick(flag)
Show/Hide
Use the setMap() method to show or hide the arrows.
// hide
ninjaArrows.setMap(null);
// show
ninjaArrows.setMap(map);Events
NinjaArrows supports two different events: arrows_created and update_finished.
- arrows_created is fired when a new instance is created and the arrows are initialised
- update_finished is fired when the arrow update has finished
- arrow_click is fired when the arrow icon was clicked
- arrow_mouseover is fired when you mouse over the arrow icon
- arrow_mouseout is fired when you mouse out the arrow icon
Use register(event, callback) to register for an event:
ninjaArrows.register("update_finished", function (event) {
// do something
};###OpenLayers
Creating a new instance
To use NinjaArrows and all its features in OpenLayers 2 simply create a new NinjaArrows instance. If a layer was specified, the arrows will be rendered on that layer. Note: The layer must be attached to a map!
var map = ... // initialize map
var layer = new OpenLayers.Layer.Vector("Arrow Layer");
map.addLayers([layer]);
var ninjaArrows = new NinjaArrows(null, layer);You can also pass an array of OpenLayers.Geometry.Point objects to the constructor.
var points = [];
// add Point-objects ...
var ninjaArrows = new NinjaArrows(points, layer);A third parameter specifies the options that can be applied to the arrows, i.e. the style:
var customStyle = {
fillColor: "white",
strokeColor: "green",
strokeWidth: 3,
textColor: "black"
};
var ninjaArrows = new NinjaArrows(points, layer, { style: customStyle });Adding and removing points
To add or remove a point call addPoint() or removePoint(). To remove all points call clearPoints().
Note: If the options paramter "projection" was specified as wgs1984, the point will be transformed to the spherical mercator projection.
var point = new OpenLayers.Geometry.Point(14, 46);
ninjaArrows.addPoint(point);
...
ninjaArrows.removePoint(point);
ninjaArrows.clearPoints();Options
The third constructor parameter may be used to apply options, i.e. a custom style, to the arrows.
style
Pass a style object to the NinjaArrows constructor or use setStyle(style) to apply a custom style. A style object defines these attributes: (If an attribute is not specified in the style object, the default property is taken.)
{
fillColor: string,
strokeColor: string,
strokeWidth: number,
textColor: string
}Dynamic Colors (v1.1+)
{
fillColor: string,
strokeColor: string,
strokeWidth: number,
textColor: string,
type: string,
colorStops: [],
resolution: number,
maximum: number
}The new style object includes type, colorStops, resolution and maximum.
type
If type property is set to gradient a gradient will be generated based on the colorStops array and the resolution. Default is default.
colorStops
The colorStops array specifies the colors used for the spectrum to be generated. A color must be a hexadecimal string.
resolution
resolution specifies the gradient's resolution.
maximum
maximum specifies the maximum an arrow's count muast have to get the last color in the spectrum.
Example:
var style = {
type: "gradient",
colorStops: ["#00CC00", "#FFFF00", "#FF0000"],
resolution: 100,
maximum 50
};When applying the style above a gradient will be generated containing 100 colors ranging from green to yellow and red. A marker with count 1 will be green, all markers with count above 50 (the maximum) will be red and the markers between will get the matching color from the gradient.
edgeOffset
This is the minimum distance in pixel between arrow at top/bottom and left/right. (Arrows won't overlap in corners). Use setEdgeOffset(offset) to change the offset. Default is 75px.
borderOffset
This is the offset from the map's border to the arrows. Use setBorderOffset(offset) to change the offset in pixel.
{
top: 0,
right: 0,
bottom: 0,
left: 70
};jumpTo
This flag specifies whether the map's bounds should extend to contain out-of-bounds markers or jump to out-of-bounds markers. Use setJumpTo(flag)
projection
The projection parameter specifies the projection of the points. Default is "sm" (spherical mercator). If projection is set to "wgs1984" points will be transformed to the spherical mercator projection.
Show and hide
To hide the arrows call setLayer function and pass null. To show the arrows pass a valid layer-object to the function.
// hide
ninjaArrows.setLayer(null);
// show
ninjaArrows.setLayer(layer);Events
NinjaArrows supports two different events: arrows_created and update_finished.
- arrows_created is fired when a new instance is created and the arrows are initialised.
- update_finished is fired when the arrow update has finished
- arrow_click is fired when the arrow icon was clicked
- arrow_mouseover is fired when you mouse over the arrow icon
- arrow_mouseout is fired when you mouse out the arrow icon
Use register(event, callback) to register for an event:
ninjaArrows.register("update_finished", function (event) {
// do something
};NinjaArrows.js includes two types of offsets: edge offset and border offset. You can specifiy these offsets through the options parameter when creating a new instance or by calling setEdgeOffset() or setBorderOffset().
Blue lines represent the edge offset. The edge offset specifies the minimum distance between arrows in corners and arrows in north, east, south and west. In other words: arrows won't overlap in the corners.
Red lines represent the border offset. The border offset specifies the distance between the arrows and the map's border. This offset can be used to position arrows so that they don't overlap map controls.
Google Maps and Openlayers
The Dynamic Colors update allows you to change the arrow's color according to its count. Everything is customizable so you can also define your own color spectrum or use the default one.
