[Map] Create Map component

[Kocal]

Q	A
Bug fix?	no
New feature?	yes
Issues	Fix #38
License	MIT

Hi :)

This PR is a proposal for #38 a replacement for #39.

Symfony UX Map is a new Symfony UX component that makes it easy to create, customize and use interactive JavaScript maps.

The package ships with:

• a simple and generic way to create a map, with markers and info-windows
• two Bridge, Leaflet and Google Maps
• a way to define provider-specific options
• a nice and fluent API
• Flex recipes are also ready: [Symfony UX Map] Create recipes for the package and its bridges recipes#1329

Example

Bridge configuration

# .env
UX_MAP_DSN=leaflet://default

# config/packages/ux_map.yaml
ux_map:
    renderer: '%env(UX_MAP_DSN)%'

Map creation

An example to render a map, custom center and zoom, some markers and info windows:

namespace App\Controller;

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\MapFactoryInterface;
use Symfony\UX\Map\Marker;
use Symfony\UX\Map\Point;

final class ContactController extends AbstractController
{
    #[Route('/contact')]
    public function __invoke(): Response
    {
            // 1. Create a new map instance
            $myMap = (new Map());
                ->center(new Point(46.903354, 1.888334))
                ->zoom(6)
            ;
    
            // 2. You can add markers, with an optional info window
            $myMap
                ->addMarker(new Marker(
                    position: new Point(48.8566, 2.3522), 
                    title: 'Paris'
                ))
                ->addMarker(new Marker(
                    position: new Point(45.7640, 4.8357), 
                    title: 'Lyon',
                    // With an info window
                    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.'
                    )
                ));
    
            // 3. And inject the map in your template to render it
            return $this->render('contact/index.html.twig', [
                'my_map' => $myMap,
            ]);
    }
}

Map rendering

You must call render_map(map) to render the map:

{{ render_map(map, { style: 'height: 700px; width: 1024px; margin: 10px' }) }}

It gives you this interactive Leaflet map:

[seb-jean]

Very useful component :)

[simondaigre]

That's awesome ! Thank you for this PR ! I checked my projects with Google Maps integration, there is some features missing here :

• allow to set a custom icon on Marker
• allow to customize map styles (styles parameter as array ?)
• on some projects I also use @googlemaps/markerclusterer. Not sure if you should include it in ux/maps but I'll do a doc PR with explanations if you want

[Kocal]

Hi @simondaigre, and thank you! :)

allow to set a custom icon on Marker

It's already on my list! I will need this feature aswell for my website where I use custom marker icons:

But I don't wanted to do too much things in a single PR. Implementing PinElement PHP-side is a small challenge which I think can already be done user-side with event listeners.

allow to customize map styles (styles parameter as array ?)

I've started to implement the API/configuration for map styles (with some classes and enums), but I've finally removed it when I knew about Cloud-based maps styling.
You can pass the mapId or call ->setMapId('...') to customize your map styles.

on some projects I also use @googlemaps/markerclusterer. Not sure if you should include it in ux/maps but I'll do a doc PR with explanations if you want

I think we would not include it in Symfony UX Map by default, a documentation would be enough IMO :)

[smnandre]

(i will make a big review this week-end ;) )

[smnandre]

A first comment before touching the real work :)

It is not possible to use Google Map without explicit consent of the user in Europe, California i think, Japan maybe, Australia too

You are of course not responsible of this, but i think some use case or implementation consequences should be discussed now

• can we expose some hook to load scripts & maps on trigger (can be the CMP or GMT for instance) ?
• can we ease the privacy compliance in any way (because as we discussed a few times with @WebMamba this is probably where some good DX can make a big difference) ?

[Kocal]

... 😮‍💨 , but yeah you're right, thanks for pointing it out.

I think the easiest way to do that is to:

• never load Google Maps maps implicitly, or at least makes it configurable server-side
  • when calling render_map(...), we won't render data-controller attribute but something else (e.g.: data-controller-wait-for-consent or something more related to Symfony UX Map), so the GoogleMaps Stimulus controller & Google Maps API won't be loaded
• provide a global function like loadSymfonyUxGoogleMaps():
  • which can be easily created on-the-fly by {{ ux_map_script_tags() }}
  • calling it will rename data-controller-wait-for-consent to data-controller, which will load the Stimulus controller & Google Maps API
• and let the developper execute loadSymfonyUxGoogleMaps() when needed

For example with the Didomi CMP:

<script>
    window.didomiOnReady = window.didomiOnReady || [];
    window.didomiOnReady.push(() => {
        function loadGoogleMapsIfConsentGiven() {
            const googleMapsPurposeId = '...';
            const googleMapsVendorId = '...';

            const userStatus = Didomi.getUserStatus();
            const enabledPurposeConsent = userStatus.purposes.consent.enabled;
            const enabledVendorConsent = userStatus.vendors.consent.enabled;

            if (enabledPurposeConsent.includes(googleMapsPurposeId) && enabledVendorConsent.includes(googleMapsVendorId)) {
                window.loadSymfonyUxGoogleMaps();
            }
        }

        if (Didomi.shouldConsentBeCollected()) {
            window.didomiEventListeners = window.didomiEventListeners || [];
            window.didomiEventListeners.push({
                event: 'consent.changed',
                listener: function (event) {
                    loadGoogleMapsIfConsentGiven();
                }
            });
        } else {
            loadGoogleMapsIfConsentGiven();
        }
    });
</script>

WDYT?

[javiereguiluz]

Do we have a list of things left to do here before making this mergeable?

Or is this fully finished and just needs a final review?

Thanks!

[Kocal]

Hi, I don't have more things to do, I've already processed the ~250+ comments :D

Final reviews are welcome of course, but I think we planned to merge this PR soonly so we can iterate on it (especially the documentation), cc @kbond @smnandre

[javiereguiluz]

It's merged now! 🎉🎉🎉

Hugo, infinite thanks for contributing this amazing new component 🙇🙇🙇 and thank you all for the nice discussion and review that you did here.

Now, let's test it in real apps, let's iterate on it and let's add good docs for the community. Thanks!

[Kocal]

Thanks @javiereguiluz :)

But we still need to set-up git repositories for UX Map bridges (Google and Leaflet), AFAIK only Fabien can do that..? Do you think we can get in touch with him? 🙏

Thanks!

[fabpot]

@Kocal Can you list what needs to be done? Based on that, I will do the magic ;)

[Kocal]

So quick! :D

We will need dedicated repositories for:

• https://github.com/symfony/ux/tree/2.x/src/Map
• https://github.com/symfony/ux/tree/2.x/src/Map/src/Bridge/Google
• https://github.com/symfony/ux/tree/2.x/src/Map/src/Bridge/Leaflet

So packages symfony/ux-map, symfony/ux-map-google and symfony/ux-map-leaflet can be published on Packagist, and so downloadable by people.

And like other Symfony components, bridges source code should not be present in symfony/ux-map repo/package.

Thanks :)

[fabpot]

Should be symfony/ux-google-map to be consistent with how we are naming bridges in Symfony.

[Kocal]

I'm working on it

[Kocal]

See #2031

[fabpot]

Should be symfony/ux-leaflet-map to be consistent with how we are naming bridges in Symfony.

[fabpot]

@Kocal All done. Can you double-check that everything has been configured properly?

[Kocal]

@fabpot thanks!
Except for the folder src/Bridge that should not be present in symfony/ux-map, everything is perfect!

[smnandre]

Cannot wait to play with it!

What an incredible PR this was, thank you very much for your patience, hard work and positive spirit @Kocal!

👏

[fabpot]

@fabpot thanks! Except for the folder src/Bridge that should not be present in symfony/ux-map, everything is perfect!

Good catch, I used Bridge like for Symfony, the src/xxx/src/yyy disturbed me :)
BUT, excluding a deep directory is NOT supported by the splitter currently. I don't remember why I put this restriction in place, so I need to double-check that.

[smnandre]

We can move folders around in the ux mono if that can ease things.

[fabpot]

All good now 🤞

[Kocal]

Thanks Fabien :)