GoogleMaps

You can easily add maps to any module item which uses a datastore - blogs, audio, custom modules, etc.

You can also add maps to a profile, and/or to your site footer.

The module uses sensible defaults, but you can override these to alter the style and functionality of each map using the additional smarty function parameters. For most usage very few parameters are actually required, but they are all detailed in the developer documentation in case you should need a higher degree of control over your maps and locations.

The module has been designed to be as simple as possible to the end user (profile owner), so it maps geocoded addresses rather than having the user enter latitude, longitude, bounds, zoom level and all the rest. As such it depends on the user entering an address or location that Google can understand, such as "12 Theoretical Street, Camden, London", or "Jamaica". As they type, the user is offered a list of possible address options to select from. When they select one their preview map is updated. They can also drag the marker, which will result in a new address from reverse geocoding.

If Google is unaware of the address (for example a newly built street), the user will have to choose the closest available address. You will find that in 99.9% of real use cases Google has you covered, and they update their databases with new addresses frequently.

As admin, or as a developer, you can add custom mapping data using the smarty function parameters, but it is important to note that this is not an "out of the box" option for your end users. They can pick addresses, countries and locations, and they can drag the marker to select a different location. To allow them to specify longitude, latitude, bounding box, zoom levels, etc you can create custom form fields using the form designer and pass those into the smarty display function instead of an item array.

Upload the module to your server.
Go to the module info tab in the admin control panel and enable it.
Add a Maps field to your item forms in Form Designer. eg audio_googlemaps or blog_googlemaps
Place the smarty function in the template where you want the map to appear.
Start adding maps using the simplest and easiest method on the planet.
Finish.

In this example we will add a map to each blog item for a single quota. You can see the results on the live demo. The procedure is exactly the same for any of the Jamroom datastore item modules, and should also be the same for third party item modules (assuming they have been coded to the same standards).

Go to Create Blog, then click on the Form Designer button.
Add a new custom field named blog_googlemaps.
In the field type dropdown select "googlemaps", check the box to allow both "create" and "update" and set the field to "active".
For this demo we are limiting the maps to a single quota, so we have selected "Maps Demo Quota" in the Groups select menu. Skip this step if you want to allow a map for every blog post.
Click the View button to return to the blog form. You should now see the googlemaps fields.

In order to display the map on the blog post we need to add the ujGoogleMaps smarty function to a template.

For this example we will add the following smarty function to /modules/jrBlog/templates/item_detail.tpl, just below the blog text, and above the share this section. You would override this template in your skin directory.

{ujGoogleMaps_map name="map" map=$item module="jrBlog" height="300"}

This would display a dynamic map showing a marker at the center. The map will be 300px high and responsive, that is to say it will fill the width of its container and the zoom level will be automatically adjusted to best show the map depending on its actual actual dimensions, so it should work well with any responsive skin across mobile, tablet and desktop.

You now have your site set up to have a map for each blog item.

To show all items on a single map (like the blog list page on the demo) see the example under Multi-item Maps.

The Map field will display a text field for entering the address or location to be shown on the map, and a preview of the map itself. Admin can configure how the initial map appears and functions, see below for more info. Note that you need to be connected to the internet to use the Google API.

To add a map to this blog post start typing an address in the maps field and select the address from the list that appears.
Try changing the address to see how the map adjusts depending on input. eg. Selecting "London, UK" will show a different map to selecting "House of Commons, London, UK".
Try dragging the marker on the map to see how the address adjusts to the new location.(not working quite right with resetting map bounds)
Click "Save" to finish creating the blog post and check out the result.

The Maps module has been designed to be as easy as possible for the end user (the profile owner). They don't need to understand latitude, longitude, bounds, zoom level etc. They simply enter an address, the possible options are shown in a typeahead dropdown, the user selects the correct address and their map is created. If they want a map of London, they can simply enter "London" and the map will be shown at the correct zoom level to best display London. If they enter a more specific address, such as "The World's End, Camden, London", the map will show at a higher zoom level. If your end users are geodata professionals and your web service needs to rely on manual entry of mapping data, this module will not work for you out of the box. Please get in touch detailing your customisation requirements. The marker in their item form map is draggable, so if they wanted to show a map of the UK with the marker on Bristol, they can do that just by dragging the marker (not currently working right).

The smarty function accepts quite a few additional parameters some of which are detailed below. Note that almost all of them are optional and you will only need to use them if you are making more complex maps or need to change the style of the maps and controls away from the defaults.

You can use the same function in jrBlog item_list.tpl just outside the foreach loop but pass in the $_items array instead of the single item. Here we make it a hybrid map and add the basic infowindow to the markers.

        {if isset($_items)}

        {ujGoogleMaps_map name="allitemsmap" map=$_items module="jrBlog" height="400" map_type="hybrid" marker="infowindow"}

            {foreach from=$_items item="item"}

This is all you will need in most situations:

{ujGoogleMaps_map module="myModule" name="map1" map=$item height="300"}

And this is all you would need for most multi-item maps:

{ujGoogleMaps_map module="myModule" name="map2" map=$_items height="300"}

Further information about multi-item maps can be found in the developer docs.

This is a summary of the most important parameters that you will encounter during common usage. They are also documented in the developer docs along with all other parameters.

We can add parameters to alter the style and controls on the map, for example adding controls="false" to remove the default google controls, map_type="hybrid" to show a different looking map, and marker="false" to hide the marker and make this more of an illustration than a tool.

{ujGoogleMaps_map name="map" map=$item module="jrBlog" height="250" controls="false" map_type="hybrid" marker="false"}

It will display a nice full width map, a large and illustrative feature on the page showing the location at its the center. You may find more styling in the Developer Docs but for really, really custom styled maps you would need to follow the Google Maps API docs and edit your javascript templates accordingly. This module will allow you to create mega-custom almost anything you like with the Google API, just add your custom javascript to display_map.tpl in the module templates directory.

Admin can control which types of map the user can choose from: Road (default), Terrain, Satellite and Hybrid. Change that setting for each quota in the module quota controls.

Add skin=true if you are displaying in a skin template.

{ujGoogleMaps_map skin=true name="map" module="ujProducts" map=$item height="600"}

Static maps use less calls to the Google API, generally load quicker and reduce potential distractions on the page as the map is not navigable. Add static=true to your function to display a static image map. You would most likely want to set an image width as well: width=500.

The maximum dimensions for a static map are 640x640 (Google Maps API for Business 2048x2048) and Static Map URLs are restricted to 2048 characters in size. Further info in Googles static maps documentation.

Note: If you explicitly set static=false in the function it will be displayed as a dynamic map even if the Force Static Maps sitewide override is on. It overrides the override. More about the API usage limits and forcing static maps sitewide here.

Some types of profile might have a location or address, for example a site or quota where each profile is a venue. In this example we will add a map for each profile and display the address and location map above the profile footer.

Go to Create Profile, then click on the Form Designer button.
Add a new custom field named profile_googlemaps.
In the field type dropdown select "googlemaps", check the box to allow both "create" and "update" and set the field to "active".
Click the View button to return to the profile form. You should now see the googlemaps fields.
To add a map, enter an address in the field and select the correct address.
Try changing the address to see how the map adjusts depending on input. eg. Selecting "London, UK" will show a different map to selecting "House of Commons, London, UK".
Click "Save" to finish creating the profile and check out the result. You now have a map for each profile stored in the database.

In order to display the map on the profile we need to add the ujGoogleMaps smarty function to a template.

For this example we will add the following smarty function to /modules/jrProfile/templates/item_detail.tpl, just above the footer.

{ujGoogleMaps_map name="map" map=$_profile module="jrProfile" height="300"}

It will display a nice full width map, a large and illustrative feature on the page showing the location of the profile as a marker in the center.

We can add parameters to alter the style and controls on the map, for example adding controls="false" to remove the default google controls, map_type="hybrid" to show a different looking map, and marker="false" to make this more of an illustration than a tool.

{ujGoogleMaps_map name="map" map=$_profile module="jrProfile" height="150" controls="false" map_type="hybrid" marker="false"}

The world of mapping and potential uses within Jamroom 5 is vast so obviously we cannot provide support for all possible use case scenarios.

The module works well with many additional developer features. These developer features work well, but they come with no assistance or support. They are well documented, and some of them are very simple to implement. But some of them are not, depending on your skills with Jamroom 5, mapping, templates, javascript, the Google Maps API, etc. Read the Developer Docs and maybe the Google Maps documentation for further details of these features and their almost endless possibilities.

Multiple items can be shown on a map, so if you have given a map location to each blog post on a quota, you can show all the locations of all the blog posts listed on a page on a single map.

Popup marker infoWindows can be added to both single marker and multi-marker maps.

You can set ujGoogleMaps to extract Exif GPS location data from photos when they are uploaded and then display sets of images on maps according to where they were taken. This works really well with multi-image modules such as jrGallery.

Maps can be set to static to reduce your calls to the Google API, and if you are close to your API usage limits you can set all maps to static sitewide using a single emergency setting.

You can use numeric coordinate map, marker and infowindow data to create highly specific maps which combine all sorts of info from your site on a map. If you need help with this sort of thing, please get in touch for a quote.

http://jam.ultrajam.net/maps-demo/blog

Temporarily here:
http://jam.ultrajam.net/googlemaps/docs

Unsupported Features here:
http://jam.ultrajam.net/googlemaps/docs/developer_docs