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.

Table of Contents

• Prerequisites
• Installation
• Usage
• Properties
• Types
• Examples

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

   import { NgxBingmapsModule } from 'ngx-bingmaps';
      
   @NgModule({
    // ...
    imports: [
      // ...
      NgxBingmapsModule
    ]
   })

2. 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. |

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

Examples

In Progress - Coming Soon