Displaying a Google Map on the Trails App Home Page and Trail List Pages

It is common to show a large Google map on the trails app home page and paginated trails list pages. That map often shows markers for the center point of each individual trail.

Below we will outline the general steps that you can use to setup this map. 

Note - you can use any map provider. We are simply using Google maps in this example. Also, this isn't the only way to integrate a map. With BranchCMS you have full control over all of your Javascript, CSS and HTML and can use a different method to load your map.

Setup the Content Template

You will first need to create a Trail List content template. See Content Templates for more information. You will also then need to configure the Trail List layout and App Home. See Layouts for more information.

Instead of creating a separate App Home content template and Trail List content template that have the same code we simply use the Trail List content template for both pages. If you have a different design for your trails app main page then feel free to use separate content templates.

Template Code

The content template will be pretty simple because we will be loading the trail data via AJAX (see Loading the Trail Data).

<h1>Trails</h1>

{** map-canvas is where the map will be displayed **}
<div id="map-canvas" style="height: 500px;"></div>

Javascript

You will need to load the Google Maps API Javascript:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY

In our example we're going to have another Javascript file called map.js that contains the code to setup the map. The intention is that this same file could be used for the trail detail, the trail list pages and the trail search results pages. In order to facilitate that we'll have another Javascript file specific to the trail list pages to set things up there.

You could load the Javascript files in your site template or, like in this example, they could be specified in the Javascript Files part of the Content Template. Doing that allows you to keep your site templates more generic and not specific to a single page type. 

We're going to add the following code to the Javascript Files field in the Content Template:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
/layout/js/map.js
/layout/js/trail-list.js

Loading the Trail Data

Many trail websites have 100+ trails that they list. For performance reasons we utilize AJAX techniques to load trail markers after the initial page has loaded. This improves performance a lot by allowing the initial page to load quickly.

Right now there are not any JSON APIs within the Trails app so we simulate that with Pages, Templates and Trail API tags.

The Template will contain nothing but the Trail API tag.

The page will be an empty page and it's only purpose is to provide a URL to call via AJAX. The result of loading that page will be the JSON provided by the content template setup below.

Create the Trail Filter API Content Template

If you didn't already create the Trail Filter API Content Template for the trail search result pages then go ahead and create a new  Trails app Content Template for the "API - Trail Filter" type. Call it "API - Trail Filter - Trail List AJAX Request".

Below is some sample code:

Create the Template

Under Design -> Templates create a new template called "AJAX Trail List". Be sure to set the "What type of content is this template?" field to "JSON" since we want the correct response headers for JSON content to be returned. 

In the template code enter the following:

{ap_api:trails:trailFilter templateId="52" getTowns="yes" getCategories="no" getCounties="no" getContacts="no" getFeatures="no" getSegments="no" instanceKey="trails"}

Change the "templateId" value to match the ID of the API - Trail Filter content template that you just created.

Change the "instanceKey" value to match the instance key for your Trails app instance.

Create the Page

Create a new page called "Trail List" with a URL of '/trail-list". Assign the "AJAX Trail List" template that you just created. 

The page does not need any content.

Javascript

We will use the same map.js Javascript that the Trail Detail page uses.

Trail-List.js

The trail-list.js file holds the setup code for just the trail list pages.