#lopeway.bindingHandlers

lopeway.bindingHandlers is a JavaScript library that includes additional binding handlers for KnockoutJS.

The binding handlers include:

• lopeway.bindingHandlers.maps.google.v2
• lopeway.bindingHandlers.maps.bing.v1

###How to use

The binding handlers depend upon KnockoutJS:

<script src="http://cloud.github.com/downloads/SteveSanderson/knockout/knockout-2.0.0.js" type="text/javascript">
</script>

and the following lopeway JavaScript utility files:

<script type="text/javascript" src="/src/lopeway.utilities.1.0.js"></script>
<script type="text/javascript" src="/src/lopeway.locations.1.0.js"></script>

####Google Maps Binding Handler

For the Google Maps binding handler, additionally reference the following script:

<script type="text/javascript" src="/src/lopeway.maps.1.0.js"></script>

and include a reference to the Google Maps (v3) API and don't forget to replace [YOUR KEY HERE] with your developer API key:

<script src="http://maps.google.com/maps/api/js?key=[YOUR KEY HERE]&sensor=false&.js" type="text/javascript"></script>

Add a container tag for the map that will be generated by Google Maps and add a 'data-bind' attribute that specifies the name you assign to the binding handler (see below) and view model properties for the configuration (config) and the methods (mapper), e.g.

<div data-bind="mapsGoogle: { config: config, mapper: mapper }"></div>

In your JavaScript, reference the lopeway.bindingHandler and assign this a name in Knockout's bindingHandlers namespace, e.g.

ko.bindingHandlers.mapsGoogle = lopeway.bindingHandlers.maps.google.v2

The view model needs to include two properties 'config', 'mapper' (corresponding to the 'config' and 'mapper' properties of the binding handler). It may seem confusing that the binding handler's property 'config' is assigned to the view model's property 'config' and, although this is the convention, you can use any name for these properties in your view model. If you change them, ensure you specify them correctly in the 'data-bind' in the HTML:

var viewModel = {
	config: {
		center: { lat: LATITUDE , lng: LONGITUDE },
		zoom: ZOOM
	},
	mapper: {}
};
ko.applyBindings(viewModel);

If applyBindings succeeds, the view model 'mapper' property will be augmented with functions for interacting with the map. In order to visualize a marker on the map, call the 'addMarker' function. The 'name' property is optional but recommended. The 'info' property is optional but, if provided describes HTML that will be displayed as an info window when the marker is clicked. The latitude (lat) and longitude (lng) properties of the marker are required.

viewModel.marker.addMarker({ name: "MyMarker", info: "<h4>MyMarker</h4>", lat: 0, lng: 0 });

The usual method for generating latitude and longitude pairs when using Google Maps is to use the Google Maps geocoder, e.g.

var geocoder = new google.maps.Geocoder();
geocoder.geocode({
	"address": "1600 Pennsylvania Ave NW  Washington, DC 20500 USA"
}, function (results, status) {
	if (status === google.maps.GeocoderStatus.OK) {
		var l = results[0].geometry.location;
		viewModel.mapper.addMarker({ name: "White House", info: "<h4>White House</h4>", lat: l.lat(), lng: l.lng() });
	}
});

####Bing Maps Binding Handler

For the Bing Maps binding handler, include a reference to the Bing Maps API (v7):

<script src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0" type="text/javascript">
</script>

Add a container tag for the map that will be generated by Bing Maps and add a 'data-bind' attribute that specifies the name you assign to the binding handler (see below) and view model properties for the configuration (config) and the methods (mapper), e.g.

<div data-bind="mapsBing: { config: config, mapper: mapper }"></div>

In your JavaScript, reference the lopeway.bindingHandler and assign this a name in Knockout's bindingHandlers namespace, e.g.

ko.bindingHandlers.mapsBing = lopeway.bindingHandlers.maps.bing.v1

The view model needs to include two properties 'config', 'mapper' (corresponding to the 'config' and 'mapper' properties of the binding handler). It may seem confusing that the binding handler's property 'config' is assigned to the view model's property 'config' and, although this is the convention, you can use any name for these properties in your view model. If you change them, ensure you specify them correctly in the 'data-bind' in the HTML:

viewModel = {
    config: {
        // Add your API developer key in place of the null on 'credentials'
        credentials: null,
        center: { lat: LATITUDE , lng: LONGITUDE },
        zoom: ZOOM,
        width: WIDTH,
        height: HEIGHT
    },
    mapper: {}
};
ko.applyBindings(viewModel);

If applyBindings succeeds, the view model 'mapper' property will be augmented with functions for interacting with the map. In order to visualize a marker on the map, call the 'addMarker' function. The 'name' property is optional but recommended. The latitude (lat) and longitude (lng) properties of the marker are required.

viewModel.marker.addMarker({ name: "MyMarker", lat: 0, lng: 0 });

The view model mapper property is augmented with a 'geocode' function that you can use to geocode addresses. The geocode function includes a callback that you can use to trigger the addition of a marker to the map:

viewModel.mapper.geocode({
    address: "1600 Pennsylvania Ave NW  Washington, DC 20500 USA",
    success: function (lat, lng) {
        viewModel.mapper.addMarker({ name: "White House", lat: lat, lng: lng });
    }
});

###Examples

####Google Maps Binding Handler

A standalone example using the lopeway.bindingHandlers.maps.google.v2 is at /examples/GoogleMaps.v2.html

####Bing Maps Binding Handler

A standalone example using the lopeway.bindingHandlers.maps.bing.v1 is at /examples/BingMaps.v1.html