Integration between Leaflet Map and CiviCRM

Provides an integration between CiviCRM api and the leaflet map. Meaning you can create maps from CiviCRM Data. You can use this plugin with Connector to CiviCRM with CiviMcRestFace plugin which gives you the ability to connect to an CiviCRM installation on a different server. Funded by CiviCoop, civiservice.de, Bundesverband Soziokultur e.V.

Usage

You can use the short code as follows:

[leaflet-civicrm-api entity=.. action=... lng_property='longitude' lat_property='latitude' profile=local tooltip_text='Name: {display_name}' ...]
<strong>{display_name}</strong>
[/leaflet-civicrm-api]

Add the short code [leaflet-map] to show the map. See https://wordpress.org/plugins/leaflet-map/ on how you can configure the [leaflet-map] short code.

The following options are possible within the tag:

Option	Required	Default value	Description
entity	Yes		The api entity in CiviCRM.
action	Yes		The api action in CiviCRM.
profile	Yes		If you have installed CiviCRM in the same wordpress site then the profile could be local otherwise use the name of the CiviMcRestFace connection.
lng_property	Yes		Fill in the property which holds the longitude value. Not required when addr_property is provided.
lat_property	Yes		Fill in the property which holds the longitude value. Not required when addr_property is provided.
addr_property	Only when lng_property and lat_property are not provided		Fill in the property which holds the address value. This plugin will then convert that address to a point on the map.
tooltip_text	No	empty	The text shown as a tooltip. You can use tokens to replace data in your text. For example "Name: {display_name}"
popup_text	No	empty	The text shown as a popup. This text can also be put inside the shortcode tag. You can use tokens to replace data in your text.
popup_property	No	empty	Property to show in the popup. For example first_name (when using the Contact.get api).
table_view	No	empty	Add this if you want the popup to hold a table with all the data.
marker_callback	No	CiviCRMLeaflet.defaultMarker	Javascript function to replace the default marker.
tooltip_callback	No	CiviCRMLeaflet.defaultTooltip	Javascript function to replace a custom tooltip text.
popup_callback	No	CiviCRMLeaflet.defaultFeature	Javascript function to replace a custom popup text.
name	No		Set a system name for this source. This name is used to identify this source. Useful if you have multiple sources in your map.
filter_header	No		Set a custom heading above the filter.
filter_button_label	No	Filter	Set a custom label for the filter button.
icon_url	No		Url to icon for the marker. For example: https://leafletjs.com/examples/custom-icons/leaf-orange.png
icon	No		Icon object for L.icon. See https://leafletjs.com/reference.html#icon. Make sure you use html entities (e.g. use [ for [ and ] for ]). An example: icon='{"iconUrl":"https://leafletjs.com/examples/custom-icons/leaf-orange.png","shadowUrl":"https://leafletjs.com/examples/custom-icons/leaf-shadow.png","iconSize":[38,95],"shadowSize":[50,64],"iconAnchor":[22,94],"shadowAnchor":[4,62],"popupAnchor":[-3,-76]}'

Tokens

The tokens are the name of the fields in the api/data processor. So for example the Contact.get api returns a field first_name and the token {first_name} will then be replaced by the content of first name.

Multiple data sources

Each short code [leaflet-civicrm-api] is displayed as a separate layer on the map. For each short code the filter fields are rendered with its own button to filter.
If you want to have a combined button for all filter fields use the following short code: [leaflet-civicrm-api-combined-filter-button filter_header='<h2>Header above button, optional</h2>' filter_button_label='Filter button label, optional'].

Customizations

Custom Markers

You can add your own javascript callback function to replace the default marker. In this function you can generate a dynamic marker based on the data returned from CiviCRM.

Below is an example function.

  function myCustomMarker (feature, latlng) {
    // See https://leafletjs.com/reference-1.7.1.html#marker
    // for more information on what kind of markers you can return.
    // For example with a custom logo when the data of contact_type is Individual is shown.
    if (feature.properties.contact_type == 'Individual') {
      var customIcon = L.icon({
        iconUrl: 'https://leafletjs.com/examples/custom-icons/leaf-orange.png',
        shadowUrl: 'https://leafletjs.com/examples/custom-icons/leaf-shadow.png',
        iconSize:     [38, 95],
        shadowSize:   [50, 64],
        iconAnchor:   [22, 94],
        shadowAnchor: [4, 62],
        popupAnchor:  [-3, -76]
      });
      return L.marker(latlng, {icon: customIcon});
    }
    return L.marker(latlng);
  };

Custom Popup

You can add your own javascript callback function to replace the default popup function so that you can even more customize the data within the popup.

Below is an example function.

  function myCustomPopup (feature, layer) {
    var text = 'Not an Individual';
    if (feature.properties.contact_type == 'Individual') {
      text = 'Individual'
    }
    if (text) {
      layer.bindPopup(text);
    }
  };

Custom Tooltip

You can add your own javascript callback function to replace the default tooltip function so that you can even more customize the text within the tooltip.

Below is an example function.

  function myCustomTooltip (feature, layer) {
    var tooltip = 'Not an Individual';
    if (feature.properties.contact_type == 'Individual') {
      tooltip = 'Individual'
    }
    if (text) {
      layer.bindTooltip(tooltip);
    }
  };

Available hooks

• integration_civicrm_leaflet_alter_filter_fields: which allows you to alter the callback functions to display a filter field. See integration_civicrm_leaflet.api.php for an example implementation.

Funded by

• CiviCooP
• Civiservice.de GmbH
• Bundesverband Soziokultur e.V.

Reporting bugs

Bugs can be reported at Github.

Contributing

The code of this plugin is published and maintained at Github. The plugin is also published at Wordpress.org and this requires that we submit each release to the Wordpress SVN

Workflow for development

1. Fork the repository at Github
2. Create a new branch for the functionality you want to develop, or for the bug you want to fix.
3. Write your code and test it, once you are finished push it to your fork.
4. Create a Pull Request at Github to notify us to merge your changes.

Workflow for creating a release

Based on the instruction from Learn with Daniel

1. Update readme.txt with the new version number (also update the Changelog section)
2. Update integration-civicrm-leaflet.php with the new version number
3. Create a new version at Github.
4. To publish the release at Wordpress Plugin directory follow the following steps:
   1. Create a temp directory: mkdir cintegration-civicrm-leaflet-tmp
   2. Go into this directory: cd cintegration-civicrm-leaflet-tmp
   3. Do an SVN checkout into SVN directory: svn checkout --depth immediates https://plugins.svn.wordpress.org/integration-between-leaflet-map-and-civicrm svn
   4. Clone the Github repository into Github directory: git clone https://github.com/CiviMRF/integration-civicrm-leaflet.git github
   5. Go into the Github directory: cd github
   6. Checkout the created release (in our example 1.0.0): git checkout 1.0.0
   7. Go into the svn directory: cd ../svn
   8. Copie the files from github to SVN: rsync -rc --exclude-from="../github/.distignore" "../github/" trunk/ --delete --delete-excluded
   9. Add the files to SVN: svn add . --force
   10. Tag the release in SVN (in our example 1.0.0): svn cp "trunk" "tags/1.0.0"
   11. Now submit to the Wordpress SVN with a message: svn ci -m 'Adding 1.0.0'

License

The plugin is licensed under AGPL-3.0.