Small Group Finder - Embedding a Map

The Small Group Finder can be configured with an embedded map. The location of your groups will be indicated on the map by pins. Clicking on a pin brings up information about the group. You can configure what information is displayed when pins are clicked.

http://i.tpsdb.com/SmallGroupFinder.png

Sample Small Group Finder with Embedded Map

Open a Google Cloud Account

To enable this feature, you will need a Google Cloud account. You can view their pricing details at https://cloud.google.com/maps-platform/pricing/sheet. An account includes a recurring $200 per month credit, making it likely that your costs will be minimal or null.

From that same pricing page, you can initiate the creation of your account by clicking on the Get Started button in the upper, right corner. When you are prompted to select the products you want, select both Maps and Places and continue with the account setup.

http://i.tpsdb.com/EnableGoogleMapsPlatform.png

Choose both Maps and Places

Create API Keys

After completing the account creation, you will need to create and configure a couple of API keys for use with your Small Group Finder map. First, double-check to make sure the needed services are enabled. Go to your new account console (https://console.cloud.google.com). If necessary, open the navigation panel on the left by clicking on the hamburger icon (the triple horizontal lines). Then go to APIs & Services > Library and ensure the following two APIs are enabled:

  • Maps JavaScript API
  • Geocoding API

Next, create two API keys at APIs & Services > Credentials. (One key may have already been created for you at account initialization.) Give the keys the following names and restrictions:

  1. touchpoint-gmap
    • This API will be used for the map display.
    • Under Application Restrictions, select HTTP Referrers (web sites) and enter your database URL followed by /*. For example, https://bellevue.tpsdb.com/*.
    • Under API Restrictions, select Restrict Key and select Maps JavaScript API.
  2. touchpoint-geocode
    • This will be used for the backend geocoding call to pull latitude and longitude.
    • Under Application Restrictions, leave the setting as None.
    • Under API Restrictions, select Restrict Key and select Geocoding API.

Add API Keys to Administration Settings

Now you will add two administration settings for the API keys you just created.

  1. Create an administration setting called GoogleMapsAPIKey and in its value copy the key named touchpoint-gmap. (Make sure you copy the key itself, not the name.)
  2. Create an administration setting called GoogleGeocodeAPIKey and in its value copy the key named touchpoint-geocode. (As above, make sure you copy the key itself, not the name.)

Test Geocoding

We recommend that you test geocoding before going further. This will demonstrate that your new Google Cloud account is operational and that your geocode API key is functioning properly. To test, create a Python script named TestGeocoding and copy the following code into it:

apiKey = model.Setting("GoogleGeocodeAPIKey")

uaddress = model.UrlEncode("SOME ADDRESS TO TEST")

val = model.RestGet("https://maps.googleapis.com/maps/api/geocode/xml?address=" + uaddress + "&sensor=false&key=" + apiKey, {})

print(val)

In the script, replace “SOME ADDRESS TO TEST” with an actual known address (e.g., the address of your church). Make sure the address you enter is within quotes as shown in the sample script. Using the main campus of the Bellevue church as an example, you would enter “2000 Appling Road, Cordova TN”. After entering the address, save the script and then run it.

If successful, the output will be information about the address, such as political areas, postal code, latitude and longitude. If this test is not successful, go back and recheck your work. Make sure you have correctly configured the API keys in your Google Cloud account and that you have accurately copied them to the TouchPoint administration settings as directed above.

Configure the Map in Small Group Finder

When you have successfully tested geocoding on your TouchPoint database, you are ready to configure your Small Group Finder to use an embedded map by completing the following steps:

Step 1

Configure the layout HTML file. If you already have a Small Group Finder, you could use your existing SGF-Layout file. But to accommodate the extra space taken up by the map, you might want to create a more streamlined layout. Below is an example:

<div class="form-group">
<h4>[SGF:Name]</h4>
<strong>Campus:</strong> [SGF:Campus]<br />
<a class="btn btn-default" href="/OnlineReg/[SGF:OrgID]">Signup</a>
<hr /></div>

The above layout will simply display the group name, on the top line, with the campus on the next line and a registration line at the bottom. You can, of course, add or change the information shown, using organization fields and extra values.

Step 2

There are additional settings, specific to the embedded map, that can be added to your main settings file, the .XML file. These additional settings should be inserted into the SGFSettings section of the file. Below are the map-specific settings, preceded by explanations. For the naming of this file and other general information, see Small Group Finder Step 4 - Create the XML File.

Enable the Embedded Map (line 5)
The crucial setting for including the map is UseEmbeddedMap. Give this setting a value of true to embed the map in your finder.
Set the Center of the Map (lines 8-9)
To set the center of the map, enter the latitude and longitude of an address near where you desire the map to be centered. In many cases, this may be the address of your church building. If you created the Python script to test geocoding, you can enter the desired location there to get the latitude and longitude. Otherwise, they can be obtained from any number of web sites, such as https://www.latlong.net.
Set the Zoom Level for the Map (line 12)
The MapZoom setting determines the zoom level for the map. The higher the number, the more you are zoomed in (larger scale, less area covered); the lower the number, the more you are zoomed out (smaller scale, more area covered). The MapZoom value must be an whole number–it cannot have a decimal component. For most applications, a value of 10 - 12 will be appropriate.
Optional Pin Marker Text (lines 16-18)
You can include text on the map pins to help easily identify a certain type of group. For example, during a certain period, you may want to make it very easy to identify groups for Financial Peace University. Using a specified extra value on those orgs, you can configure the MarkerText settings so that an “F” is displayed on all the pins for groups offering FPU. Omit these lines if you will not use this feature.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<?xml version="1.0" encoding="utf-8"?>
<SGF divisionid="14,18" layout="SGF-Layout" shell="SGF-Shell">
    <SGFSettings>
        <!-- this is the setting that puts the map in your Finder -->
        <SGFSetting name="UseEmbeddedMap" value="true" />

        <!-- the center of the map -->
        <SGFSetting name="Latitude" value="32.7567879" />
        <SGFSetting name="Longitude" value="-97.0728131" />

        <!-- the zoom level for the map -->
        <SGFSetting name="MapZoom" value="12" />

        <!-- these optional settings go together for the marker text... so, for orgs with
             a "Group Term" == "FPU" then show "F" on the map pin -->
        <SGFSetting name="MarkerTextName" value="Group Term" />
        <SGFSetting name="MarkerTextValue" value="FPU" />
        <SGFSetting name="MarkerText" value="F" />
    </SGFSettings>

    <!-- the list of filters that are used for searching... the name is the org extra value -->
    <SGFFilters>
        <!-- note the "exclude" attribute - this is if there are org extra values that shouldn't be shown -->
        <SGFFilter name="Campus" title="Congregation" locked="false" lockedvalue="" exclude="Undecided,Do Not Attend" />
        <SGFFilter name="Group Type" title="Group Type" locked="false" lockedvalue="" />
        <SGFFilter name="Group Term" title="Beta / Community Group" locked="false" lockedvalue="" />
        <SGFFilter name="Childcare" title="Childcare" locked="false" lockedvalue="" />
    </SGFFilters>
</SGF>
Step 3

Map pins will indicate the locations of the groups in the finder. When you click on the head of a pin, a small dialog box displays information about the group. The default information shown in the dialog may not be what you desire and, in fact, may reference information that is not provided on your organizations.

To configure the information you would like to be displayed, create an HTML special content file named SGF-MapToolTip. This file is similar to the Layout file, indicating what group information to show and how it should be organized. Below is an example HTML Snippet:

<strong>[SGF:Name]</strong><br />
<img src="[SGF:LeaderPicSrc]" width="128" /><br />
[SGF:Leader]<br />
[SGF:Day] at [SGF:Time]<br />
<a href="/OnlineReg/[SGF:OrgID]" style="line-height: 1.6;" target="_blank">Signup</a>

Explanation of Map Pin Locations

By default the pin locations on the map will indicate the address of the group leader. Optionally, you can add to the XML file the setting ExtraValueHost and set its value to the name of an organization extra value that you place on all the groups and that contains the host address for the group. You can give this extra value the name of your choice (for example, SGF:HostAddress).

Optional Settings

Below are some optional administration settings associated with the Small Group Finder You can find these settings at Administration > Settings, on the Features tab, in the Small Group Finder section.

SecureProfilePictures
For security reasons, viewing profile pictures requires you to log in. Set this value to false to override this security feature and allow leader photos to be displayed in the Small Group Finder, viewable by those not logged in.
SGF-LoadAllExtraValues
By default, the Small Group Finder utilizes only extra values that begin with the prefix SGF:. Set this to true to load all extra values for use with the finder. You might do this so that you can make use of pre-existing extra values that were created without the SGF: prefix.
UX-MapPinTextColor
Use this setting to set the text color within the Small Group Finder map pin (hexadecimal RGB).
UX-MapPinColor-Campus-x

If your church has multiple campuses, you can specify the color map pins should be for a certain campus. In the name of the setting, the final ‘x’ should be replaced by the desired campus ID. The value given the setting should be the six-digit hexadecimal RGB code for the desired color. For example, if your Main campus has and ID of 2 and you want the map pins for Main campus groups to be orange, create the setting UX-MapPinColor-Campus-2 with a value of ffa500.

Note

To find the IDs for your campuses, go to Administration > Lookup Codes and select Campus from the Organization panel.



Latest Update 03/6/2020

Correct line numbers on the explanations in Step 2



Recent Update 03/5/2020

Removed the sample code and explanations for optional XML settings that are included in Small Group Finder Step 4 - Create the XML File

© 2020 TouchPoint Software, LLC.  All rights reserved.