Ngx-bingmaps NPM

Bing Maps - Angular

A simple and modular library for displaying Bing Maps inside an angular application.

The library is designed to be lightweight, relying on the official Bing Maps V8 Web Control SDK as a dependency. Its purpose is to alleviate the challenges of integrating Bing Maps into your Angular Projects.

Head to the PlayGround for a brief demonstration of the capabilities of ngx-bingmaps.

Prerequisites

To utilize this library completely, you will need a Bing Maps API key. You can acquire a free API key for testing or development purposes by visiting the Bing Maps Dev Center.

Installation

npm is the easiest and fastest way to get started using ngx-bingmaps

npm install ngx-bingmaps --save

Usage

To incorporate the library into your Angular Project, simply follow the instructions provided below. 1. Add the NgxBingmapsModule into your project's module imports

```typescript
import { NgxBingmapsModule } from 'ngx-bingmaps';

@NgModule({
 // ...
 imports: [
   // ...
   NgxBingmapsModule
 ]
})
```

Use the ngx-bingmaps in your angular components HTML as below.
```
<ngx-bingmaps [apiKey]="apiKey" [pushpins]="pushpins"></ngx-bingmaps>
```
For apiKey use the key acquired in the Prerequisites section. The pushpins variable represents an array of object of type PushpinModel. For a complete list of properties, kindly refer to the Properties section.

Properties

Defines the input properties of the component.

Name	Type	Default	Description
`apiKey`	string	null	Your Bing Maps API key.
`height`	string	"100%"	The map defaults to 100% height and width of parent element.
`mapType`	string	"road"	This enumeration is used to specify the type of map style that should be displayed by the map. Such as `aerial`, `birdseye`, and `road` etc. For all available options please refer: Bing Maps V8 Web Control - MapTypeId Enumeration
`navigationBarMode`	string	"square"	The NavigationBarMode can be used to customize the layout and style of the navigation bar. Such as `compact`, `minified`, and `square` etc. For all available options please refer: Bing Maps V8 Web Control - NavigationBarMode Enumeration
`pushpins`	array of type PushpinModel	`[]`	Pushpins, are the markers used for marking location(s) on the map.
`width`	string	"100%"	The map defaults to 100% height and width of parent element.

Types

Defines the custom types used by the library.

PushpinModel

Pushpins, sometimes also referred to as markers or MapIcons on other mapping platforms, are one of the primary ways of marking a location on a map. The PushpinModel has the following properties.

Name	Type	Default	Description
`location`	object of type GeolocationModel	null	The geolocation for the pushpin on Map.
`options`	object of type PushpinOptionsModel	null	Various options available for creating personalized pushpins.
`infobox`	object of type PushpinInfoboxModel	null	Various options available for creating personalized infoboxes.

GeolocationModel

GeolocationModel represents the coordinate information needed to mark locations on a map. The GeolocationModel consists of two properties: latitude and longitude.

The latitude property is used to represent how far north or south a location is. This value is an angle measured around the center of the earth from the equator towards the poles. A positive value is in the northern hemisphere and a negative value is in the southern hemisphere. This value has a range of -90 to 90 degrees however due to the mathematics involved in representing the spherical globe as a flat 2D map, some calculations approach infinity as you approach polar latitudes. To avoid this, Bing Maps and many other mapping platforms that use the Mercator projection system clip the latitude coordinates to approximately -85 and 85 degrees.

The longitude property stores the angle of horizontal offset from the prime meridian (0 degrees). This property has a value between -180 and 180 degrees.

Name	Type	Description
`latitude`	number	The latitude of the location.
`longitude`	number	The longitude of the location.

PushpinOptionsModel

The following pushpin option properties can be used to create customized pushpins.

Name	Type	Default	Description
`color`	string	null	Specifies what color to make the default pushpin.
`cursor`	string	"pointer"	The css cursor to show when pushpin has mouse events on it.
`draggable`	boolean	null	A boolean indicating whether the pushpin can be dragged to a new position with the mouse or by touch.
`enableClickedStyle`	boolean	null	Specifies whether to enable the clicked style on the pushpin. To unselect a pushpin, simply click it again. Alternatively, you can disable then re-enable this property.
`enableHoverStyle`	boolean	null	Specifies whether to enable the hover style on the pushpin.
`icon`	string	null	Defines the the icon to use for the pushpin. This can be a URL to an Image or SVG file, an image data URI, or an inline SVG string. Tip: When using inline SVG, you can pass in placeholders `{color}` and `{text}` in your SVG string. This placeholder will be replaced by the pushpins color or text property value when rendered. Note: SVG’s are converted into a static image before being rendered as a pushpin. As such embedded images should use data URI’s and not links to files as the file will not load before the SVG is rendered. CSS classes are also not supported on SVG’s, however inline styles are.
`subTitle`	string	null	A secondary title label value to display under the pushpin. Uses label collision detection. This label automatically changes color between white and dark grey depending on which map style is selected. Requires the title label to be set.
`title`	string	null	The title label value to display under the pushpin. This label automatically changes color between white and dark grey depending on which map style is selected. Pushpin Titles support label collision detection, as described below.
`text`	string	null	A short string of text that is overlaid on top of the pushpin.
`visible`	boolean	`true`	A boolean indicating whether to show or hide the pushpin. The default value is true. A value of false indicates that the pushpin is hidden, although it is still an entity on the map.

These options are derived, and subset of Bing Maps V8 Web Control - PushpinOptions Object.

PushpinInfoboxModel

The following infobox option properties can be used to create customized infoboxes.

Name	Type	Default	Description
`closeDelayTime`	number	0	The number of milliseconds to wait before closing an infobox when the visible option is changed from true to false.
`description`	string	null	The string displayed inside the infobox.
`htmlContent`	string	null	The HTML that represents the infobox. Note that some infobox options are ignored if custom HTML is set (title, description, maxHeight, maxWidth, actions, showCloseButton, showPoint). Also, if custom HTML is used to represent the infobox, the infobox is anchored at the top-left corner.
`maxHeight`	number	126	The maximum size that the infobox height can expand to based on it’s content.
`maxWidth`	number	256	The maximum size that the infobox width can expand to based on it’s content.
`showCloseButton`	boolean	`true`	A boolean indicating whether to show the close dialog button on the infobox. By default, the close button is displayed as an X in the top right corner of the infobox. This property is ignored if custom HTML is used to represent the infobox.
`showPointer`	boolean	`true`	A boolean indicating whether to display the infobox with a pointer. In this case the infobox is anchored at the bottom point of the pointer. If this property is set to false, the infobox is anchored at the bottom left corner. This property is ignored if custom HTML is used to represent the infobox.
`title`	string	null	The title of the infobox.
`visible`	boolean	`true`	A boolean indicating whether to show or hide the infobox. A value of false indicates that the infobox is hidden, although it is still an entity on the map.
`zIndex`	number	null	The z-index of the infobox with respect to other items on the map.