px-map.html

<!--
Copyright (c) 2018, General Electric

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

<!--
    Relative paths assume component is being run from inside an app or another component, where dependencies are flat
    siblings. When this component is run from its own repo (e.g. tests, examples), we assume the server is started with
    'gulp serve' (or similar server setup) to enable correct finding of bower dependencies for local runs.
-->
<link rel="import" href="../polymer/polymer.html"/>

<!-- Load required PxMapBehaviors -->
<link rel="import" href="px-map-behavior-root.html">

<!-- Import style modules -->
<link rel="import" href="css/px-map-leaflet-styles.html">
<link rel="import" href="css/px-map-styles.html">

<!--
`px-map` is a lightweight framework for building interactive maps with web
components and Polymer. The framework includes a base mapping component
(`<px-map>`) that can be used with many different subcomponents to solve
common mapping UI problems, like plotting geographic data.

### Usage

#### Example: Basic map

Below is a simple example with little configuration that will display a map
centered on Tokyo, Japan:

    <px-map lat="35.6895" lng="139.6917" zoom="12" style="width: 500px; height: 300px;">
      <px-map-tile-layer url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"></px-map-tile-layer>
      <px-map-control-zoom position="bottomright"></px-map-control-zoom>
    </px-map>

This example uses the `<px-map>` base component to draw a map and center it on
a specific location when it first loads.

If we stopped there and didn't add any subcomponents, the map would load, draw itself,
and center on Tokyo, but we would only see a gray background. The map needs a
base layer — some underlying imagery that shows road networks or satellite imagery
or terrain information. In this example, we use the `<px-map-tile-layer>` subcomponent
to load imagery from an OpenStreetMap tile layer service showing the road network
and other points of interest.

Finally, we use the `<px-map-control-zoom>` subcomponent to add a zoom control
that lets the user click or tap buttons to zoom in and out of the map.

#### Example: Visualizing geospatial data

Plotting geospatial data on the map is easy — just choose the right subcomponent
to show the information you have. For example, we can plot two points-of-interest
in Tokyo using static markers:

    <px-map fit-to-markers style="width: 500px; height: 300px;">
      <px-map-tile-layer url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"></px-map-tile-layer>
      <px-map-control-zoom position="bottomright"></px-map-control-zoom>

      <px-map-layer-group name="Landmarks">
        <px-map-marker-static lat="35.6763976" lng="35.6763976">
          <px-map-popup-info title="Meiji Jingu" description="Shinto shrine dedicated to the Emperor Meiji and Empress Shoken."></px-map-popup-info>
        </px-map-marker-static>
        <px-map-marker-static lat="35.6654861" lng="139.7706668">
          <px-map-popup-info title="Tsukiji Market" description="Sprawling wholesale fish market with an array of seafood & viewing areas for a popular tuna auction."></px-map-popup-info>
        </px-map-marker-static>
      </px-map-layer-group>
    </px-map>

This example sets up a `<px-map>` base component that will automatically set its
location and zoom level to fit the markers we added. It adds a basic tile layer
(`<px-map-tile-layer>`) and zoom control (`<px-map-zoom-control>`).

To plot related points of interest, we use the `<px-map-layer-group>` and give
it a descriptive name. We add markers with geographic data that describes their
location using `<px-map-marker-static>`. To give users more information about
each point, we add popups to both markers with the name and description of the
place they represent using `<px-map-popup-info>`.

### Styling
The following custom properties are available for styling:

Custom property | Description
:----------------|:-------------
`--px-map-z-index` | Configurable z-index to position `px-map` within your app

### What you can do with px-map

Out of the box, `px-map` includes the basic things needed to draw and plot data
on an interactive map. It is also extensible — development teams are encouraged
to build their own subcomponents that add features needed for their application.

The following components are available:

Base map

- `<px-map>`: Draws the underlying map, sets location/zoom and notifies updates when the user interacts with the map, enables and disables interactions, orchestrates subcomponents

Tile layers

- `<px-map-tile-layer>`: Calls a tile service API to fetch underlying tile images for the map

Overlay/visualization layers

- `<px-map-layer-group>`: Groups related overlays together to allow for bulk interactions (e.g. hide all in the group)
- `<px-map-marker-static>`: Creates a marker that shows the state of a point/asset (e.g. with color)
- `<px-map-marker-symbol>`: Creates a marker with an icon that shows the state of a point/asset
- `<px-map-marker-locate>`: Creates a marker that represents the user's location
- `<px-map-marker-group>`: Draws many markers in clusters, useful for visualizing thousands of points that can be dynamically updated

UI components

- `<px-map-popup-info>`: Binds a popup that can include text or an image to markers
- `<px-map-popup-data>`: Binds a popup that can include text and key/value data to markers

Controls

- `<px-map-control-zoom>`: Adds zoom buttons the user can tap to zoom in or out
- `<px-map-control-scale>`: Adds a scale that shows the distance of an area on the map in miles/kilometers
- `<px-map-control-locate>`: Adds a button the user can tap to locate themselves on the map and center the map on their location

The current major release (v1.X) is focused on providing essential controls,
tile layer API support, and on plotting point-based data (e.g. markers) and
updating the point data in real time. Support for drawing lines, polygons, and
other geospatial data representations hasn't been added to the framework and will
require some extensions if needed. New subcomponents will be added over time.

### What's under the hood

The current major release of `px-map` uses the open source Leaflet library to
support displaying a map with base tiles and geospatial overlays. Future iterations of
the component may offer the ability to use a different library in place of
Leaflet, while keeping the same basic API.

### Choosing a tile server

Most px-map demos use the OpenStreetMap public tile service to serve map tiles
(e.g. `https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png`) with the px-map-tile-layer
subcomponent. This tile service is used for demo purposes only. You should not use
this tile service for production applications; you will need to implement or
purchase your own tile service.

The [OpenStreetMap Tile Usage Policy](https://operations.osmfoundation.org/policies/tiles/)
details specific restrictions for developers using their public tile service.
These restrictions include the following provision: "Heavy use (e.g. distributing
an app that uses tiles from openstreetmap.org) is forbidden without prior
permission". If you choose to use the OpenStreetMap service for demos or development,
you should likely replace the service URLs when your app is shipped to production.

The following list of companies provide tile service APIs that may be free or
paid and should be compatible with the px-map-tile-layer (note that these are
not endorsed, but just offered as options):

  - [Mapbox](https://www.mapbox.com/help/how-mapbox-data-works/)
  - [Carto](https://carto.com/location-data-services/basemaps/)
  - [Mapzen](https://mapzen.com/products/maps/)

You can also use the px-map-tile-layer-bing component to load map tiles from the Bing API.

@element px-map
@blurb A lightweight framework for building interactive maps with web components
@homepage index.html
@demo index.html
-->

<dom-module id="px-map">
  <template>
    <!-- Vendor style modules to provide base styling -->
    <style include="px-map-leaflet-styles"></style>

    <!-- This should always be the last style module imported to override default styles -->
    <style include="px-map-styles"></style>

    <style>
      /* By default, just fill container */
      :host {
        display: block;
        position: relative;
      }
      :host #map {
        position: absolute;
        width: 100%;
        height: 100%;
        z-index: var(--px-map-z-index, auto);
      }
      /* Use flex to resize */
      :host([flex-to-size]) {
        display: flex;
        flex: 1;
      }
      :host([flex-to-size]) #map {
        flex: 1;
      }
    </style>
    <div id="map"></div>
    <slot></slot>
  </template>
</dom-module>
<script>
  Polymer({
    is: 'px-map',
    behaviors: [PxMapBehavior.LeafletRoot]
  });
</script>