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
Create an administration setting named SGF-UseEmbeddedMap and set its value to true.
Step 2

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 3

When using the embedded map, a special HTML shell is required. The name of the shell is referenced in the Small Group Finder configuration file (the .XML file). The name itself does not matter, but a recommendation is SGF-Shell. Below is example code that can be used. The crucial element is the container division where the map goes.

<html>
<head>
    <title>Group Finder</title>
    <link href="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css" rel="stylesheet" /><meta content="width=device-width, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" name="viewport" />
</head>
<body>
<div class="container"><!-- CONTAINER -->
<footer>Small Group Footer</footer>
</div>
</body>
</html>
Step 4

There are additional settings, specific to the embedded map, that can be placed in your main setting file, the .XML file. Below is sample code for the file, preceded by explanations of the settings related to the map. For the naming of this file and other general information, see Small Group Finder Step 4 - Create the XML File.

Optional Subtitle Text (line 7)
If you wish to include text under your Small Group Finder title, you can create an HTML special content file and include the desired text. Then use the Subtitle-Content setting to point to the HTML file.
Set the Center of the Map (lines 10-11)
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 14)
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 appropriate.
Exclude Groups from the Finder (lines 17-18)
You may want to exclude certain groups in the specified division from appearing in the Small Group Finder. A group might be full, for example, or only intended for participants that you invite. You can use the ShowOnly… settings to define an additional criterion for inclusion in the group finder.
Optional Pin Marker Text (lines 21-23)
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.
 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
30
31
32
33
34
<?xml version="1.0" encoding="utf-8"?>
<SGF layout="SGF-Layout" shell="SGF-Shell">
    <SGFSettings>
        <SGFSetting name="Title" value="Community Groups" />

        <!-- optional setting for a subtitle -->
        <SGFSetting name="Subtitle-Content" value="SGF-Subtitle" />

        <!-- 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 settings go together to provide exclusions for certain orgs... so only those with an org extra value of "Status" == "Open" will show up -->
        <SGFSetting name="ShowOnlyName" value="Status" />
        <SGFSetting name="ShowOnlyValue" value="Open" />

        <!-- these settings go together for the marker text... so, for orgs with a "Group Term" == "Beta Group" then show "B" on the map pin -->
        <SGFSetting name="MarkerTextName" value="Group Term" />
        <SGFSetting name="MarkerTextValue" value="Beta Group" />
        <SGFSetting name="MarkerText" value="B" />
    </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 5

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:

[SGF:Name]<br />
[SGF:HostAddress]<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 the administration setting SGF-ExtraValueHost and set its value to the name of an organization extra value that you place on all the group and that contains the host address for the group. You can give this extra value the name of your choice. For example, in the sample code for the SGF-MapToolTip shown above, the pin location is defined by the extra value SGF:HostAddress.

Optional Settings

Here are some optional administration settings associated with the Small Group Finder:

SGF-OrgTypes
To include only organizations of a specified Organization Type in the group finder, add this administration setting with a value of the desire Organization Type. For example, to include only groups of the type Community Groups, give the setting the value Community Groups.
UX-SGFSortBy
Use this setting to specify a particular extra value field to sort the groups in the finder. For example, if you give this setting the value SGF:Neighborhood, the groups will be sorted alphabetically by the values in the SGF:Neighborhood extra value.
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.

© 2019 TouchPoint Software, LLC.  All rights reserved.