px-map-control-locate.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"/>

<!-- Local dependencies -->
<link rel="import" href="px-map-behavior-control.html">

<!--
The locate control creates a button that the user can tap to center the map
on her current location. Pair this control with the `px-map-control-zoom` component
to give the user multiple options for navigating the map.

This control relies on the user's browser to expose API methods for finding
the user's location. Some browsers implement this API differently and have
unique restrictions on when it can be called. Generally, the page calling
the location API must be served over HTTPS, and the browser usually pops up
a permissions box to confirm the user wants to share their location.

See the MDN article on browser geolocation API usage for more information on
how your app must be configured to use it: https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/Using_geolocation

### Usage

    <px-map>
      <px-map-tile-layer url='https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'></px-map-tile-layer>
      <px-map-control-locate move-to-location position="bottomright"></px-map-control-locate>
    </px-map>

When the user taps on the button in the example above, the map will automatically
set its center to the user's detected location (if it is successfully found).

### Drop a marker on the user's location

Use this marker together with the `px-map-marker-locate` component to automatically
drop a marker at the latitude and longitude of user's current location:

    <px-map lat="12" lng="13" zoom="15">
      <px-map-tile-layer url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"></px-map-tile-layer>

      <px-map-control-locate last-found-location="{{location}}" move-to-location position="bottomright"></px-map-control-locate>
      <px-map-marker-locate lat="{{location.lat}}" lng="{{location.lng}}" accuracy="{{location.accuracy}}"></px-map-marker-locate>
    </px-map>

Data-binding to the `lastFoundLocation` attribute and listening for changes is
a useful way to update the state of your app or other map components with the
user's current location.

### Handling location events and failure

If your app doesn't meet the requirements for the user's browser to respond to the
locate request, the control will stop trying to find their location and dispatch
an error event. Ideally, you should listen for this error event (which will include
a message describing the reason for the failure) and notify the user that their
location can't be found (e.g. with an alert message).

Bind an event listener to the `px-map-control-locate-error` event to handle a
failure and notify the user:

    <px-map>
      <px-map-control-locate id="locate" position="bottomright"></px-map-control-locate>
    </px-map>
    <script>
      var control = document.querySelector('#locate');
      control.addEventListener('px-map-control-locate-error', function(evt) {
        // do something with `evt.message` to notify the user ...
      });
    </script>

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

Custom property | Description
:----------------|:-------------
`--px-map-control-button-background-color` | Background color for the map control buttons
`--px-map-control-button-text-color` | Text color for the map control buttons
`--px-map-control-button-border-width` | Border width for the map control buttons
`--px-map-control-button-border-color` | Border color for the map control buttons
`--px-map-control-button-background-color--hover` | Background color for the map control buttons when hovered
`--px-map-control-button-text-color--hover` | Text color for the map control buttons when hovered
`--px-map-control-button-border-color--disabled` | Border color for the map control buttons when disabled
`--px-map-control-button-text-color--disabled` | Text color for the map control buttons when disabled

@element px-map-control-locate
@blurb ...
@homepage index.html
@demo index.html
-->

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