Skip to content

Commit

Permalink
[Map] Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@smnandre
smnandre committed Nov 4, 2024
1 parent 708693d commit a2f4b13
Showing 1 changed file with 165 additions and 86 deletions.
251 changes: 165 additions & 86 deletions src/Map/doc/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,18 @@ Configuration is done in your ``config/packages/ux_map.yaml`` file:
The ``UX_MAP_DSN`` environment variable configure which renderer to use.

Map renderers
~~~~~~~~~~~~~

The Symfony UX Map bundle supports multiple renderers. A map renderer is a
service that provides the code and graphic assets required to render and
interact with a map in the browser.

Available renderers
~~~~~~~~~~~~~~~~~~~

UX Map ships with two renderers: `Google Maps`_ and `Leaflet`_.

============== ===============================================================
Renderer
============== ===============================================================
Expand All @@ -49,104 +58,173 @@ Renderer
**DSN**: ``UX_MAP_DSN=leaflet://default`` \
============== ===============================================================

Usage
-----
.. tip::

Read the `Symfony UX Map Leaflet bridge docs`_ and the
`Symfony UX Map Google Maps brige docs`_ to learn about the configuration
options available for each renderer.

Creating and rendering
~~~~~~~~~~~~~~~~~~~~~~
Create a map
------------

A map is created by calling ``new Map()``. You can configure the center, zoom, and add markers::
namespace App\Controller;
A map is created by calling ``new Map()``. You can configure the center, zoom, and add markers.
Start by creating a new map instance::
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\UX\Map\InfoWindow;
use Symfony\UX\Map\Map;
use Symfony\UX\Map\Marker;

// Create a new map instance
$myMap = (new Map());

Center and zoom
~~~~~~~~~~~~~~~

You can set the center and zoom of the map using the ``center()`` and ``zoom()`` methods:

use Symfony\UX\Map\Map;
use Symfony\UX\Map\Point;

final class HomeController extends AbstractController
{
#[Route('/')]
public function __invoke(): Response
{
// 1. Create a new map instance
$myMap = (new Map())
// Explicitly set the center and zoom
->center(new Point(46.903354, 1.888334))
->zoom(6)
// Or automatically fit the bounds to the markers
->fitBoundsToMarkers()
;
$myMap

// 2. You can add markers
$myMap
->addMarker(new Marker(
position: new Point(48.8566, 2.3522),
title: 'Paris'
))

// With an info window associated to the marker:
->addMarker(new Marker(
position: new Point(45.7640, 4.8357),
title: 'Lyon',
infoWindow: new InfoWindow(
headerContent: '<b>Lyon</b>',
content: 'The French town in the historic Rhône-Alpes region, located at the junction of the Rhône and Saône rivers.'
)
))

// You can also pass arbitrary data via the `extra` option in both the marker
// and the infoWindow; you can later use this data in your custom Stimulus controllers
->addMarker(new Marker(
// ...
extra: [
'icon_mask_url' => 'https://maps.gstatic.com/mapfiles/place_api/icons/v2/tree_pinlet.svg',
],
infoWindow: new InfoWindow(
// ...
extra: [
'num_items' => 3,
'includes_link' => true,
],
),
)
;

// 3. You can also add Polygons, which represents an area enclosed by a series of `Point` instances
$myMap->addPolygon(new Polygon(
points: [
new Point(48.8566, 2.3522),
new Point(45.7640, 4.8357),
new Point(43.2965, 5.3698),
new Point(44.8378, -0.5792),
// Explicitly set the center and zoom
->center(new Point(46.903354, 1.888334))
->zoom(6)

// Or automatically fit the bounds to the markers
->fitBoundsToMarkers()
;

Add markers
~~~~~~~~~~~

You can add markers to a map using the ``addMarker()`` method:

$myMap
->addMarker(new Marker(
position: new Point(48.8566, 2.3522),
title: 'Paris'
))

// With an info window associated to the marker:
->addMarker(new Marker(
position: new Point(45.7640, 4.8357),
title: 'Lyon',
infoWindow: new InfoWindow(
headerContent: '<b>Lyon</b>',
content: 'The French town in the historic Rhône-Alpes region, located at the junction of the Rhône and Saône rivers.'
)
))

// You can also pass arbitrary data via the `extra` option in both the marker
// and the infoWindow; you can later use this data in your custom Stimulus controllers
->addMarker(new Marker(
// ...
extra: [
'icon_mask_url' => 'https://maps.gstatic.com/mapfiles/place_api/icons/v2/tree_pinlet.svg',
],
infoWindow: new InfoWindow(
// ...
extra: [
'num_items' => 3,
'includes_link' => true,
],
infoWindow: new InfoWindow(
content: 'Paris, Lyon, Marseille, Bordeaux',
),
));

// 4. And inject the map in your template to render it
return $this->render('contact/index.html.twig', [
'my_map' => $myMap,
]);
}
}
),
)
;

Add Polygons
~~~~~~~~~~~~

You can also add Polygons, which represents an area enclosed by a series of ``Point`` instances:

$myMap->addPolygon(new Polygon(
points: [
new Point(48.8566, 2.3522),
new Point(45.7640, 4.8357),
new Point(43.2965, 5.3698),
new Point(44.8378, -0.5792),
],
infoWindow: new InfoWindow(
content: 'Paris, Lyon, Marseille, Bordeaux',
),
));

Render a map
------------

To render a map in your Twig template, use the ``ux_map`` Twig function, e.g.:

To be visible, the map must have a defined height:

.. code-block:: twig
{# to be visible, the map must have a defined height #}
{{ ux_map(my_map, { style: 'height: 300px' }) }}
{# you can add custom HTML attributes too #}
You can add custom HTML attributes too:

.. code-block:: twig
{{ ux_map(my_map, { style: 'height: 300px', id: 'events-map', class: 'mb-3' }) }}
Extend the default behavior
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Twig Function ``ux_map()``
~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``ux_map()`` Twig function allows you to create and render a map in your Twig
templates. The function accepts the same arguments as the ``Map`` class:

.. code-block:: html+twig

{{ ux_map(
center: [51.5074, 0.1278],
zoom: 3,
markers: [
{ position: [51.5074, 0.1278], title: 'London' },
{ position: [48.8566, 2.3522], title: 'Paris' },
{
position: [40.7128, -74.0060],
title: 'New York',
infoWindow: { content: 'Welcome to <b>New York</b>' }
},
],
attributes: {
class: 'foo',
style: 'height: 800px; width: 100%; border: 4px solid red; margin-block: 10vh;',
}
) }}

Twig Component ``<twig:ux:map />``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Alternatively, you can use the ``<twig:ux:map />`` component.

.. code-block:: html+twig

<twig:ux:map
center="[51.5074, 0.1278]"
zoom="3"
markers='[
{"position": [51.5074, 0.1278], "title": "London"},
{"position": [48.8566, 2.3522], "title": "Paris"},
{
"position": [40.7128, -74.0060],
"title": "New York",
"infoWindow": {"content": "Welcome to <b>New York</b>"}
}
]'
attributes='{
"class": "foo",
"style": "height: 800px; width: 100%; border: 4px solid red; margin-block: 10vh;"
}'
/>

The ``<twig:ux:map />`` component requires the `Twig Component`_ package.

.. code-block:: terminal
$ composer require symfony/ux-twig-component
Interact with the map
~~~~~~~~~~~~~~~~~~~~~

Symfony UX Map allows you to extend its default behavior using a custom Stimulus controller:

Expand Down Expand Up @@ -219,18 +297,19 @@ Symfony UX Map allows you to extend its default behavior using a custom Stimulus
}
}
.. tip::

Read the `Symfony UX Map Leaflet bridge docs`_ and the
`Symfony UX Map Google Maps brige docs`_ to learn about the exact code
needed to customize the markers.
Then, you can use this controller in your template:

.. code-block:: twig
{{ ux_map(my_map, { 'data-controller': 'mymap', style: 'height: 300px' }) }}
.. tip::

Read the `Symfony UX Map Leaflet bridge docs`_ and the
`Symfony UX Map Google Maps brige docs`_ to learn about the exact code
needed to customize the markers.

Backward Compatibility promise
------------------------------

Expand Down

0 comments on commit a2f4b13

Please sign in to comment.