px-map-marker-group.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-marker-group.html">

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

<!--
This subcomponent lets the user load a large number of markers onto her map, and
groups the marker in clusters based on proximity. These clusters are updated as
the user zooms in and out of the map.

### Usage

    <px-map fit-to-markers flex-to-size>
      <px-map-tile-layer url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"></px-map-tile-layer>
      <px-map-marker-group name="Plaques" data="{{geoJSON}}"></px-map-marker-group>
    </px-map>

### Defining your FeatureCollection and Features

The `data` attribute expects a GeoJSON feature collection (http://geojson.org/geojson-spec.html)
with specific settings configured to draw each marker.

#### FeatureCollection Format

The root JavaScript Object passed to the `data` attribute should be a FeatureCollection
object with the following keys/values:

- {String} `type`: Must be 'FeatureCollection'
- {Array}  `features`: An array of feature objects

The feature collection should be formatted like this:

    {
      "type": "FeatureCollection",
      "features": [...]
    }

These are required settings. Not including them or mis-formatting them will result
in your marker group failing to draw. (An error may be logged to the console with
a descripton of the issue if it is found. Some formatting issues may not be
caught and cause a silent failure or an exception to be raised.)

#### Feature Format

Each entry in the FeatureCollection array should be a JavaScript Object formatted
as a Feature with the following keys/values:

- {String} `type`: Must be 'Feature'
- {Number} `id`: A unique numeric ID. If the feature is changed, it should keep its ID. No other features in the collection should have the same ID.
- {Object} `geometry`
- {String} `geometry.type`: Must be 'Point'
- {Array}  `geometry.coordinates`: a pair of coordinates in `[lng,lat]` order
- {Object} `properties`
- {Object} `properties.marker-icon`: Settings to configure a marker icon
- {Object} `properties.marker-popup`: [OPTIONAL] Settings to configure a marker icon

For example, here is a feature that is drawn with a "static" marker icon (from `px-map-marker-static`):

    {
      "type": "Feature",
      "id": 748082,
      "geometry": {
        "type": "Point",
        "coordinates": [-117.273809,32.840128]
      },
      "properties": {
        "marker-icon": {
          "icon-base": "static-icon",
          "icon-type": "info"
        }
      }
    }

#### Defining the marker icon

The `properties.marker-icon` object should describe the type of marker
icon that should be drawn and the settings for that marker icon.

Define the marker icon base using the `properties.marker-icon.icon-base` property.
Choose from any of the built-in markers provided with `px-map`:

- 'static-icon'
- 'symbol-icon'

To configure the icon, pass additional settings in the format
`properties.marker-icon.icon-[SETTING]` in dash case. For example,
this would configure the feature to use a "symbol" marker icon
with a briefcase symbol and the warning color:

    {
      "type": "Feature",
      "id": 984093,
      "geometry": {
        "type": "Point",
        "coordinates": [-110.948009,37.984995]
      },
      "properties": {
        "marker-icon": {
          "icon-base": "symbol-icon",
          "icon-icon": "px-fea:cases",
          "icon-type": "warning"
        }
      }
    }

See the API documentation pages for the `px-map-marker-*` components
for more information on what markers icons and settings are available.

#### The `icon-type` is special

The `properties.marker-icon.icon-type` property is special and is used for more
than configuring the type setting of your chosen marker. This setting also defines
the color this marker will be represented as in a cluster. See the `colorsByType`
property documentation for more information on choosing your own colors
for each type. By default, the following colors will be used:

- 'unknown': gray
- 'info': blue
- 'warning': yellow
- 'important': red

#### Binding a popup

Popups can also be bound to individual markers inside the marker group. The
popup will be opened when the user clicks on the un-clustered marker.

(It will not open if the user clicks on the cluster icon that contains the marker.
Popups cannot be bound to cluster icons.)

Use the `properties.marker-popup` object to describe the type of popup that should
be attached and the settings for that popup.

Define the popup base using the `properties.marker-popup.popup-base` property.
Choose from any of the built-in popups provided with `px-map`:

- 'info-popup'
- 'data-popup'

To configure the popup, pass additional settings in the format
`properties.marker-popup.popup-[SETTING]` in dash case. For example,
this would configure the feature to use an "info" popup with a title
and description text:

    {
      "type": "Feature",
      "id": 984093,
      "geometry": {
        "type": "Point",
        "coordinates": [-110.948009,37.984995]
      },
      "properties": {
        "marker-icon": {
          "icon-base": "static-icon",
          "icon-type": "info"
        },
        "marker-popup": {
          "popup-base": "info-popup",
          "popup-title": "Title here",
          "popup-description": "Lorem ipsum dolor sit amet, consectetur adipisicing..."
        }
      }
    }

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

Custom property | Description
:----------------|:-------------
`--px-map-icon-border-color` | Border color for map markers
`--px-map-icon-unknown-color` | Marker color for 'unknown' type markers
`--px-map-icon-info-color` | Marker color for 'info' type markers
`--px-map-icon-warning-color` | Marker color for 'warning' type markers
`--px-map-icon-important-color` | Marker color for 'important' type markers
`--px-map-color-custom-0` | 	These are the colors used to represent the markers with a "custom-n" icon type. Custom colors MUST start at 0 and cannot contain gaps between numbers. You may define custom type markers up to `custom-100`.
`--px-map-color-custom-1` |
`--px-map-color-custom-2` |
`--px-map-color-custom-n` |
`--px-map-marker-group-cluster-path-size` | Width of the "donut" for a marker group cluster
`--px-map-marker-group-cluster-font-size` | Font size for the label inside of a cluster
`--px-map-marker-group-cluster-font-color` | Font color for the label inside of a cluster
`--px-map-marker-group-cluster-font-weight` | Font weight for the label inside of a cluster
`--px-map-marker-group-cluster-line-height` | Line height for the label inside of a cluster
`--px-map-marker-group-cluster-border-size` | Width of the border around a cluster
`--px-map-marker-group-cluster-border-color` | Color of the border around a cluster
`--px-map-marker-group-cluster-polygon-stroke-color` | Stroke color for the polygon behind a cluster
`--px-map-marker-group-cluster-polygon-fill-color` | Fill color for the polygon behind a cluster
`--px-map-marker-group-cluster-background-color` | Background color for the cluster

@element px-map-marker-group
@blurb ...
@homepage index.html
@demo index.html
-->

<dom-module id="px-map-marker-group">
  <template>
    <style include="px-map-styles"></style>
    <style>
      :host {
        display: none;
      }
    </style>
  </template>
</dom-module>
<script>
  Polymer({
    is: 'px-map-marker-group',
    behaviors: [PxMapBehavior.MarkerGroup]
  });
</script>