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:: https://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:: https://i.tpsdb.com/EnableGoogleMapsPlatform.png :target: # Choose both Maps and Places .. _CreateAPIKeys: 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/*`. If you have a custom domain, you will need to add it also, using the same format. For example, `https://my.bellevue.org/*`. * 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 --------------------------------------- Navigate to `Administration > Settings > Features > Small Group Finder & Family Map` for the API keys you just created. #. For the setting named **Google Maps API Key**, enter the value for the key named **touchpoint-gmap**. (Make sure you copy the key itself, not the name.) #. For the setting named **Google Geocode API Key**, enter the value for 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: .. code-block:: python 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: .. code-block:: HTML
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 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 :doc:`SmallGroupFinderStep4`. 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. .. code-block:: xml :linenos: