Skip to content

Commit e52a4b0

Browse files
smnandresmnandre
committed
[Map] Update documentation
1 parent ecbf1b3 commit e52a4b0

File tree

1 file changed

+165
-86
lines changed

1 file changed

+165
-86
lines changed

‎doc/index.rst

Lines changed: 165 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -37,9 +37,18 @@ Configuration is done in your ``config/packages/ux_map.yaml`` file:
3737
3838
The ``UX_MAP_DSN`` environment variable configure which renderer to use.
3939

40+
Map renderers
41+
~~~~~~~~~~~~~
42+
43+
The Symfony UX Map bundle supports multiple renderers. A map renderer is a
44+
service that provides the code and graphic assets required to render and
45+
interact with a map in the browser.
46+
4047
Available renderers
4148
~~~~~~~~~~~~~~~~~~~
4249

50+
UX Map ships with two renderers: `Google Maps`_ and `Leaflet`_.
51+
4352
============== ===============================================================
4453
Renderer
4554
============== ===============================================================
@@ -49,104 +58,173 @@ Renderer
4958
**DSN**: ``UX_MAP_DSN=leaflet://default`` \
5059
============== ===============================================================
5160

52-
Usage
53-
-----
61+
.. tip::
62+
63+
Read the `Symfony UX Map Leaflet bridge docs`_ and the
64+
`Symfony UX Map Google Maps brige docs`_ to learn about the configuration
65+
options available for each renderer.
5466

55-
Creating and rendering
56-
~~~~~~~~~~~~~~~~~~~~~~
67+
Create a map
68+
------------
5769

58-
A map is created by calling ``new Map()``. You can configure the center, zoom, and add markers::
59-
60-
namespace App\Controller;
70+
A map is created by calling ``new Map()``. You can configure the center, zoom, and add markers.
71+
Start by creating a new map instance::
6172
62-
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
63-
use Symfony\Component\HttpFoundation\Response;
64-
use Symfony\Component\Routing\Attribute\Route;
65-
use Symfony\UX\Map\InfoWindow;
6673
use Symfony\UX\Map\Map;
67-
use Symfony\UX\Map\Marker;
74+
75+
// Create a new map instance
76+
$myMap = (new Map());
77+
78+
Center and zoom
79+
~~~~~~~~~~~~~~~
80+
81+
You can set the center and zoom of the map using the ``center()`` and ``zoom()`` methods:
82+
83+
use Symfony\UX\Map\Map;
6884
use Symfony\UX\Map\Point;
6985

70-
final class HomeController extends AbstractController
71-
{
72-
#[Route('/')]
73-
public function __invoke(): Response
74-
{
75-
// 1. Create a new map instance
76-
$myMap = (new Map())
77-
// Explicitly set the center and zoom
78-
->center(new Point(46.903354, 1.888334))
79-
->zoom(6)
80-
// Or automatically fit the bounds to the markers
81-
->fitBoundsToMarkers()
82-
;
86+
$myMap
8387

84-
// 2. You can add markers
85-
$myMap
86-
->addMarker(new Marker(
87-
position: new Point(48.8566, 2.3522),
88-
title: 'Paris'
89-
))
90-
91-
// With an info window associated to the marker:
92-
->addMarker(new Marker(
93-
position: new Point(45.7640, 4.8357),
94-
title: 'Lyon',
95-
infoWindow: new InfoWindow(
96-
headerContent: '<b>Lyon</b>',
97-
content: 'The French town in the historic Rhône-Alpes region, located at the junction of the Rhône and Saône rivers.'
98-
)
99-
))
100-
101-
// You can also pass arbitrary data via the `extra` option in both the marker
102-
// and the infoWindow; you can later use this data in your custom Stimulus controllers
103-
->addMarker(new Marker(
104-
// ...
105-
extra: [
106-
'icon_mask_url' => 'https://maps.gstatic.com/mapfiles/place_api/icons/v2/tree_pinlet.svg',
107-
],
108-
infoWindow: new InfoWindow(
109-
// ...
110-
extra: [
111-
'num_items' => 3,
112-
'includes_link' => true,
113-
],
114-
),
115-
)
116-
;
117-
118-
// 3. You can also add Polygons, which represents an area enclosed by a series of `Point` instances
119-
$myMap->addPolygon(new Polygon(
120-
points: [
121-
new Point(48.8566, 2.3522),
122-
new Point(45.7640, 4.8357),
123-
new Point(43.2965, 5.3698),
124-
new Point(44.8378, -0.5792),
88+
// Explicitly set the center and zoom
89+
->center(new Point(46.903354, 1.888334))
90+
->zoom(6)
91+
92+
// Or automatically fit the bounds to the markers
93+
->fitBoundsToMarkers()
94+
;
95+
96+
Add markers
97+
~~~~~~~~~~~
98+
99+
You can add markers to a map using the ``addMarker()`` method:
100+
101+
$myMap
102+
->addMarker(new Marker(
103+
position: new Point(48.8566, 2.3522),
104+
title: 'Paris'
105+
))
106+
107+
// With an info window associated to the marker:
108+
->addMarker(new Marker(
109+
position: new Point(45.7640, 4.8357),
110+
title: 'Lyon',
111+
infoWindow: new InfoWindow(
112+
headerContent: '<b>Lyon</b>',
113+
content: 'The French town in the historic Rhône-Alpes region, located at the junction of the Rhône and Saône rivers.'
114+
)
115+
))
116+
117+
// You can also pass arbitrary data via the `extra` option in both the marker
118+
// and the infoWindow; you can later use this data in your custom Stimulus controllers
119+
->addMarker(new Marker(
120+
// ...
121+
extra: [
122+
'icon_mask_url' => 'https://maps.gstatic.com/mapfiles/place_api/icons/v2/tree_pinlet.svg',
123+
],
124+
infoWindow: new InfoWindow(
125+
// ...
126+
extra: [
127+
'num_items' => 3,
128+
'includes_link' => true,
125129
],
126-
infoWindow: new InfoWindow(
127-
content: 'Paris, Lyon, Marseille, Bordeaux',
128-
),
129-
));
130-
131-
// 4. And inject the map in your template to render it
132-
return $this->render('contact/index.html.twig', [
133-
'my_map' => $myMap,
134-
]);
135-
}
136-
}
130+
),
131+
)
132+
;
133+
134+
Add Polygons
135+
~~~~~~~~~~~~
136+
137+
You can also add Polygons, which represents an area enclosed by a series of ``Point`` instances:
138+
139+
$myMap->addPolygon(new Polygon(
140+
points: [
141+
new Point(48.8566, 2.3522),
142+
new Point(45.7640, 4.8357),
143+
new Point(43.2965, 5.3698),
144+
new Point(44.8378, -0.5792),
145+
],
146+
infoWindow: new InfoWindow(
147+
content: 'Paris, Lyon, Marseille, Bordeaux',
148+
),
149+
));
150+
151+
Render a map
152+
------------
137153

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

156+
To be visible, the map must have a defined height:
157+
140158
.. code-block:: twig
141159
142-
{# to be visible, the map must have a defined height #}
143160
{{ ux_map(my_map, { style: 'height: 300px' }) }}
144161
145-
{# you can add custom HTML attributes too #}
162+
You can add custom HTML attributes too:
163+
164+
.. code-block:: twig
165+
146166
{{ ux_map(my_map, { style: 'height: 300px', id: 'events-map', class: 'mb-3' }) }}
147167
148-
Extend the default behavior
149-
~~~~~~~~~~~~~~~~~~~~~~~~~~~
168+
169+
Twig Function ``ux_map()``
170+
~~~~~~~~~~~~~~~~~~~~~~~~~~
171+
172+
The ``ux_map()`` Twig function allows you to create and render a map in your Twig
173+
templates. The function accepts the same arguments as the ``Map`` class:
174+
175+
.. code-block:: html+twig
176+
177+
{{ ux_map(
178+
center: [51.5074, 0.1278],
179+
zoom: 3,
180+
markers: [
181+
{ position: [51.5074, 0.1278], title: 'London' },
182+
{ position: [48.8566, 2.3522], title: 'Paris' },
183+
{
184+
position: [40.7128, -74.0060],
185+
title: 'New York',
186+
infoWindow: { content: 'Welcome to <b>New York</b>' }
187+
},
188+
],
189+
attributes: {
190+
class: 'foo',
191+
style: 'height: 800px; width: 100%; border: 4px solid red; margin-block: 10vh;',
192+
}
193+
) }}
194+
195+
Twig Component ``<twig:ux:map />``
196+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
197+
198+
Alternatively, you can use the ``<twig:ux:map />`` component.
199+
200+
.. code-block:: html+twig
201+
202+
<twig:ux:map
203+
center="[51.5074, 0.1278]"
204+
zoom="3"
205+
markers='[
206+
{"position": [51.5074, 0.1278], "title": "London"},
207+
{"position": [48.8566, 2.3522], "title": "Paris"},
208+
{
209+
"position": [40.7128, -74.0060],
210+
"title": "New York",
211+
"infoWindow": {"content": "Welcome to <b>New York</b>"}
212+
}
213+
]'
214+
attributes='{
215+
"class": "foo",
216+
"style": "height: 800px; width: 100%; border: 4px solid red; margin-block: 10vh;"
217+
}'
218+
/>
219+
220+
The ``<twig:ux:map />`` component requires the `Twig Component`_ package.
221+
222+
.. code-block:: terminal
223+
224+
$ composer require symfony/ux-twig-component
225+
226+
Interact with the map
227+
~~~~~~~~~~~~~~~~~~~~~
150228

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

@@ -219,18 +297,19 @@ Symfony UX Map allows you to extend its default behavior using a custom Stimulus
219297
}
220298
}
221299
222-
.. tip::
223-
224-
Read the `Symfony UX Map Leaflet bridge docs`_ and the
225-
`Symfony UX Map Google Maps brige docs`_ to learn about the exact code
226-
needed to customize the markers.
227300
228301
Then, you can use this controller in your template:
229302

230303
.. code-block:: twig
231304
232305
{{ ux_map(my_map, { 'data-controller': 'mymap', style: 'height: 300px' }) }}
233306
307+
.. tip::
308+
309+
Read the `Symfony UX Map Leaflet bridge docs`_ and the
310+
`Symfony UX Map Google Maps brige docs`_ to learn about the exact code
311+
needed to customize the markers.
312+
234313
Backward Compatibility promise
235314
------------------------------
236315

0 commit comments

Comments
 (0)