Skip to content

Gmarker Snippet

Jump to bottom Edit New page
Everett Griffiths edited this page Feb 10, 2015 · 5 revisions

Gmarker is a simplified version of the getResources Snippet (from which it borrows several parameters). Gmarker uses latitude/longitude coordinates contained on MODX pages to draw markers on a map (e.g. for a store locator). Use it when your MODX pages contain location information that you would like to display graphically on a map. For example, your pages might contain TVs for address, city, state, and zip.

Map with Markers

Parameters

The Gmarker Snippet uses some of the same parameters as the Gmap Snippet, but this Snippet will place markers on the map — this can be used for store locator functionality.

  • &latlng (string) latitude,longitude coordinates (comma-separated) defining the map center. Overrides &address. If omitted, the map will be centered on the first result.

  • &address (string) address representing the center of the map. If omitted, the map will be centered on the first result.

  • &height (string) desired map height (specify px or % — v1 was pixels only). Defaults to System Setting gmarker.default_height.

  • &width (string) desired map width (specify px or % — v1 was pixels only). Defaults to System Setting gmarker.default_width.

  • &id (string) the CSS id of the outputted div (identified by &outTpl). Defaults to map

  • &class (string) the CSS class of the outputted div (identified by &outTpl). Default is empty.

  • &zoom (integer) default is 15.

  • &type ROADMAP | TERRAIN | SATELLITE the type of map you wish to generate. Default: ROADMAP

  • &headTpl (string) optional Chunk name. The referenced Chunk is what is piped into your document head. Default: gmarkershead

  • &markerTpl (string) optional Chunk name. The referenced Chunk contains Javascript variables defining a google.maps.Marker object. Default: gmarker

  • &resultTpl (string) optional Chunk name. The referenced Chunk contains HTML to format a single search result (i.e. a blurb) describing a corresponding pin on the map. &showResults must be set to 1, and somewhere on the calling page, you must use the "gmarker.results" placeholder. Default: gresult

  • &outTpl (string) optional Chunk name used to process the final output (usually just a div tag which gets written to via Javascript). Default: g_out

  • &showResults (boolean) if set, a list will be generated with a blurb of text for each pin. The &resultTpl formats each result. Somewhere on the calling page, you must use the "gmarker.results" placeholder: the list will be written to that placeholder. Default: 0

  • &secure connect using HTTPS. Defaults to System Setting.

  • &showDeleted (boolean) Borrowed from getResources

  • &showUnpublished (boolean) Borrowed from getResources

  • &showHidden (boolean) Borrowed from getResources

  • &hideContainers (boolean) Borrowed from getResources

  • &limit (integer) Borrowed from getResources

  • &tvPrefix (string) Borrowed from getResources. Default: '' (empty string). NOTE: getResources uses a default of "tv."!

  • &resources (string) Borrowed from getResources. Comma-seprated list of resources.

  • &parents (string) Borrowed from getResources. Comma-seprated list of parent folders whose children contain location information.

  • &templates (integer) Comma-separated list of template IDs. This is useful if you only want to return results that use a given template(s).

  • &tvName (string) name of a TV that you want to filter by. Used in conjunction with &tvValue

  • &tvValue (string) comma-separated list of valid values. A record must have one of the listed values in the TV specified by &tvName for it to be included in the result set. Used in conjunction with &tvName. E.g. if &tvName is "color" and &tvValue is "red,blue,green", then only records that are red, blue, or green will be returned.

  • &shadow (boolean) Should each pin have a shadow? If set to 0, then the [[+shadow]] placeholder will include a value of '"flat":true,' (Your markerTpl must include appropriate code). Default: 1

  • &drop (boolean) Should pins be dropped onto the map? If set to 1, then the [[+drop]] placeholder will contain a value of '"animation": google.maps.Animation.DROP,'. Default: 0

  • &info (boolean) should an info window be shown? Default: 1

  • &infoTpl (string) name of Chunk used to display an info window on click. Default: ginfo. &info must be set to 1.

  • &suppressLookup (boolean) by default, any resources turned up by the query that do not contain latitude and longitude information will trigger a call to the Google Geocoding API. This is done so that the latitude and longitude information can be looked up and saved automatically in much the same way as the Geocoding Plugin. With large result sets, however, this behavior can trigger a landslide of lookups and result in a very slow page load. Default: 0.

  • &group (string) the name of a resource field or TV that should be used to group results into colors. For example, if you want pins to be colored according to zipcode, then you might use "&group=`zipcode`" in your snippet call.

  • &checkbox (boolean) if set to 1, the placeholder "gmarker.checkboxes" will contain checkboxes to control the showing/hiding of groups of pins on the map. The &group option should also be set. Default: 0

  • &groupCallback (string) name of a snippet that will alter the returned group names. This is useful if you need to perform grouping on a field that is stored as an id (e.g. a categories stored as page ids). By using a callback function, you can convert the page ids to the category names (e.g. to the "pagetitle"). The snippet should accept a parameter named "group" and return a string.

  • &debug (integer) if you set this to 1, the SQL query will be returned. The &address or the &latlng parameter are REQUIRED to center the map!

Retrofitting

A powerful feature of this Snippet is its ability to look up the latitude and longitude coordinates of any page that is queried. This is useful if you had pages on your site before you installed the Gmarker AddOn. Normally, saving a page will rely on the Geocoding Plugin to perform the latitude/longitude lookups, but the Gmarker Snippet can perform this action in bulk so long as the &suppressLookup parameter is not set to 1.

Warning
 it can take a long time to perform multiple geocoding lookups! So the first time you run the Gmarker snippet might take a long time, and the map may fail to load. Rest assured: each lookup is cached, and the results are written back to the pages so the long execution time should only occur the first time you run the Snippet. Remember: once your pages have latitude and longitude information saved to them, the Google Geocoding API is not needed.

Examples

Simplest Example

For example, if your MODX site had a folders for pages 12, 13, and 14, each folder containing pages with address information, then the following would create a map with markers for each location:

[[Gmarker? &address=`New York,NY` &parents=`12,13,14` &zoom=`7`]]

Note that the &address or &latlng parameter is required to center the map!

Searching by TV

Say for example you want your map to show all locations that share a particular TV value, e.g. all locations in the same zipcode.

[[Gmarker? &latlng=`[[*latitude]],[[*longitude]]` &templates=`8` &zoom=`8`
&tvName=`zipcode` &tvValue=`90042` ]]

This will show all pages that are using template 8 and are in the 90042 zip code.

Showing checkboxes

In this example, we want checkboxes to show/hide groups of markers. Each page (using template 8) has a TV named "category", which stores a page ID (we’re using a Resource TV).

[[Gmarker? &latlng=`[[*latitude]],[[*longitude]]` &templates=`8` &zoom=`8`
&checkbox=`1` &group=`category` &groupCallback=`getCategoryName` ]]

Remember: if you want to use the checkbox option, you should set the following 3 parameters together:

  • &checkbox

  • &group

  • &groupCallback

Since our TV stores an integer page ID, we are going to use a callback function (referenced by &groupCallback) to convert the value into something useful.

Your Callback Snippet

In this example, we name our snippet getCategoryName:

<?php
/**
 * @param string $group  -- the name of the group.  When &group=`category`, this is a page id
 * @return string a page title
 */
$page = $modx->getObject('modResource', $group);
if ($page) {
   return $page->get('pagetitle');
}
else {
   return 'Unknown';
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally