1. Benötigte Erweiterungen und Plugins installieren
Im Civi benötigst Du:
- Eine funktionierende Geocodierung – z.B. durch die Geocoder Extension und
- die Data Processor Extension.
Im WordPress:
- Leaflet Map – dieses Plugin integriert LeafletJS in WordPress und ermöglicht es, benutzerdefinierte Karten z.B. über OpenStreetMap anzuzeigen.
- Das Plugin Integration between Leaflet Map and CiviCRM für dessen Anbindung an CiviCRM.
Wenn Du die Karte auf einer externen Website einrichten möchtest – also CiviCRM nicht auf der selben WordPress-Instanz läuft – musst Du noch etwas mehr vorbereiten:
Konfiguration von CiviMcRestFace (optional):
- Installiere das Plugin Connector to CiviCRM with CiviMcRestFace – dieses verbindet die API-Schnittstelle Deines Civi mit der externen Website (und kann auch für andere Anwendungen genutzt werden, z.B. für das Plugin Caldera Forms CiviCRM integration).
- Erstelle einen CiviCRM-Benutzer, der als API-Benutzer für die API-Verbindung zu Deinem CiviCRM verwendet werden soll.
- Erzeuge einen API-Key für diesen Nutzer (hier eine Anleitung dazu auf StackExchange)
- Beschränke die Berechtigungen für den API-Benutzer auf den API-Zugriff (vielleicht musst Du dafür eine neue Benutzerrolle erstellen).
- Gehe in den WordPress-Einstellungen auf CiviCRM McRestFace Connections und wähle unter CiviCRM Connector „Remote connection“ aus.
- Gib die CiviCRM Rest URL ein – Wichtig: Diese URL wird eventuell von den in den CiviCRM Einstellungen oder in der offiziellen Doku angegebenen Beispielen abweichen und dieses Muster haben: https://mein-civi.de/wp-json/civicrm/v3/rest
- Gib Deinen CiviCRM Site Key ein – er steht in der civicrm.settings.php.
- Gib den erzeugten API key ein und speichere die Verbindung ab.
2. Einen Data Processor anlegen
Wir werden nun eine API-Entität erstellen, die dann das Leaflet-Integration-Plugin verwenden kann, um die Daten für unsere Partnerkarte abzurufen. Mit Hilfe der Data Processor Extension ist das ein relativ einfaches Unterfangen. Stelle zunächst sicher, dass wir alle benötigten Daten haben:
- Füge ein benutzerdefiniertes Feld für Kontakte hinzu, das ein Auswahlfeld für die Partnerschaftsstufen Bronze, Silber und Gold enthält.
- Füge ein weiteres benutzerdefiniertes Feld für eine Logo-URL hinzu (eine Datei wäre auch möglich).
- Lege einige Kontakte mit Daten in diesen Feldern an und prüfe, dass auch die Geodaten für die hinterlegten Anschriften berechnet wurden.
Gehe nun zu Administration → Data Processor → Add Data Processor und folge den nächsten Schritten:
Datenquellen (Data Sources) erstellen
Wähle „Datenquelle hinzufügen“ und wähle „Kontakt“ als Quelle. Du kannst bei Bedarf auch Filter festlegen, z. B. die Abfrage auf einen Kontakttyp beschränken. In unserem Beispiel wähle für das Auswahlfeld zur Partnerschaft die Option „Ist nicht leer“, da wir nur die Kontakte haben möchten, die auch eine Partnerschaft ausgewählt haben:
Jetzt brauchen wir noch die Geodaten, um die Pins auf unserer Karte zu lokalisieren. Diese Daten gehören zur Adresse und deshalb müssen wir eine zweite Datenquelle hinzufügen. Tippe erneut auf „Datenquelle hinzufügen“ und wähle dieses Mal „Adresse“. Wähle unter „Join with other sources“ die Kontakt-ID in den Dropdowns für „Join on field“.
Ausgabefelder (Output Fields) hinzufügen
Erstelle die Pflichtfelder für Längen- und Breitengrad mit „Feld hinzufügen“ und wähle aus Ausgabeformat „Raw field value“ und dann ::Breitengrad (bzw. ::latitude) oder ::Längengrad (bzw. ::longitude) unter Feld. Achte darauf, dass Du immer einfache und aussagekräftige Namen als Systemnamen wählst, da diese später als Token verwendet werden (manchmal können die automatisch generierte Namen recht lang sein, ersetzten Umlaute usw.).
Füge nun die übrigen Felder hinzu, die wir auf unserer Karte in den Popups sehen möchten:
Filter erstellen
Wir wollen unsere Karte nach dem Partner-Level filterbar machen, also müssen wir einen Feldfilter für dieses Feld hinzufügen:
Achte darauf, dass „Filter is exposed to the user“ aktiviert ist, damit die Auswahl am Ende auch für den Nutzer angezeigt wird.
Die Ausgabe (Output) konfigurieren
Füge unter „Select output“ eine Ausgabe vom Typ API hinzu und gib der API-Entität einen Namen:
Du könntest nun noch zur Kontrolle den API-Explorer verwenden, um zu sehen, was die Ausgabe CiviCRMPartnerMap ist, oder eine andere Ausgabe vom Typ Kontaktsuche für diesen Zweck erstellen, aber der CiviCRM-Teil ist jetzt erledigt!
3. Erstellen von Shortcodes zum Einbinden der Karte
Jetzt müssen wir nur noch eine Karte erstellen und sie mit der API verbinden.
Erstelle zunächst eine neue Seite oder einen Beitrag unter Wordpress und füge einen Shortcode für das Leaflet Map Plugin ein, um die Karte selbst hinzuzufügen:
[leaflet-map lat=50 lng=12 zoom=6 zoomcontrol !detect-retina]
In der Leaflet Map Konfiguration findest Du eine Seite mit dem Namen „shortcode helper“, die Dir dabei hilft, die Karte korrekt zu konfigurieren.
Gib nun den folgenden Shortcode für die Leaflet / CiviCRM Integration ein:
[leaflet-civicrm-api entity=CiviCRMPartnerMap action=get lng_property='longitude' lat_property='latitude' profile=local][/leaflet-civicrm-api]
Die Tag-Optionen im Shortcode, sind Pflichtangaben und haben die folgenden Bedeutungen:
- entity → die API-Entität, die wir mit dem Data Processor erstellt haben
- action → die API-Action get
- lng_property → Systemname für das gewählte Längengradfeld, hier: ‚longitude‘
- lat_property → Systemname für das gewählte Breitengradfeld, hier: ‚latitude‘
- profile → Wenn Du CiviCRM auf der gleichen WordPress-Instanz installiert hast, kann das Profil „local“ sein, andernfalls verwende hier den Namen der CiviMcRestFace-Verbindung (siehe Kapitel Konfiguration von CiviMcRestFace oben)
Wenn Du Deinen WordPress-Post so veröffentlichst, sollte die Karte bereits die Pins anzeigen und auch der Filter sollte funktionieren. Was noch fehlt, sind die Popups mit zusätzlichen Informationen. Um diese zu erhalten, füge nun noch die folgende Option zum Tag hinzu:
popup_text='<img src="{logo}"><br/><strong>Name: </strong>{display_name}<br><strong>Partnership Level: </strong>{partnership_level}'
Wie Du siehst werden einfach die Systemnamen der Datenprozessorfelder als Tags verwendet, begleitet von einigen einfachen HTML-Tags. Die vollständigen Shortcodes lauten jetzt:
[leaflet-map lat=50 lng=12 zoom=6 zoomcontrol !detect-retina]
[leaflet-civicrm-api entity=CiviCRMPartnerMap action=get lng_property='longitude' lat_property='latitude' profile=local popup_text='<img src="{logo}"><br/><strong>Name: </strong>{display_name}<br><strong>Partnership Level: </strong>{partnership_level}'][/leaflet-civicrm-api]
Voilà!
Feedback ist herzlich willkommen.
Weiterführende Infos:
- Alle Optionien für die shortcodes und weitere Anpassungsmöglichkeiten sind hier auf Englisch zu finden: GitHub - CiviMRF/integration-civicrm-leaflet: Integration between leaflet maps and CiviCRM API.
- Eine englischsprachige Version dieser Anleitung findest Du hier.
