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. .. figure:: http://i.tpsdb.com/SmallGroupFinder.png :target: # 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. .. figure:: http://i.tpsdb.com/EnableGoogleMapsPlatform.png :target: # 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: #. **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**. #. **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. #. 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.) #. 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::

[SGF:Name]

Campus: [SGF:Campus]
Signup
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. .. seealso:: :doc:`SmallGroupFinderStep2` 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. :: Group Finder
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 :doc:`SmallGroupFinderStep4`. 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. .. code-block:: xml :linenos: 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]
[SGF:HostAddress]
[SGF:Day] at [SGF:Time]
Signup 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.