Using Simple Locator

Requirements

Simple locator requires PHP version 5.4.0 or above, and WordPress version 3.8 or above. The plugin will not install on setups that do not meet the minimum requirements.

Displaying the Form

The Shortcode

Embed a search form with the [wp_simple_locator] shortcode. The following options are available:

Example: The form in the sidebar on this page uses the following shortcode: 

[wp_simple_locator 
distances="5,10,20,50,100" 
mapcontainer="#fullpage-map" 
buttontext="icon-search" 
addresslabel="U.S. Zip Code or City"
mapcontrols="show" 
resultscontainer="#mapresults" 
mapcontrolsposition="RIGHT_BOTTOM"
placeholder="Enter U.S. Location"]

The Widget

Options include the title, distance options, and the map height. To use the widget outside of a predefined sidebar area, use the following function in your template, as outlined in the WordPress documentation. The widget name is SimpleLocator\Widgets\Form (must include namespaces).

the_widget( 'SimpleLocator\API\FormWidget', 'map_height=150' );

Try the Widget

Theme Templates

To manually call the form in theme templates, use the do_shortcode function WordPress provides:

$shortcode = '[wp_simple_locator distances="5,10,20,50,100" mapcontainer="#fullpage-map" buttontext="search" addresslabel="Zip Code or City" mapcontrols="show" resultscontainer="#mapresults" mapcontrolsposition="RIGHT_BOTTOM"]';
echo do_shortcode($shortcode);

Single View Maps

Automatic Content Filtering

By default, a map of the location is added to the content on singular views. To remove this feature, update the setting under Simple Locator > General Settings.

Shortcode

The following shortcode displays a map for a single location. If no post id is provided, and the shortcode is used on a singular view template, the current location will be used.

[wp_simple_locator_map post="post_id" additionalfields="hide"]

All Locations Map

To display a map with all locations, use the shortcode [simple_locator_all_locations].
Important: If your database contains a very large number of locations, using this shortcode will result in a slow page load. This functionality is best reserved for sites with a limited number of locations.

JavaScript Functions

Simple Locator uses the Google Maps API for all map functionality. The following JavaScript callback functions are available for customizing the map and results: 

/**
* Returns the Google Maps response object on geocode success 
*/
wpsl_googlemaps_response(){}

/**
* Runs after the map and results have fully rendered
* @param active_form - DOM object for the form being submitted
*/
wpsl_after_render(active_form){}

/**
* Runs on map marker click event
* @param marker - Google Maps marker object
* @param i - index of marker
* @param active_form - DOM object for the form being submitted
*/
wpsl_click_marker(marker, i, active_form){}

/**
* Runs if no results were returned in the query
* @param location - The formatted address for the search area
* @param active_form - DOM object for the form being submitted
*/
wpsl_no_results(location, active_form){}

/**
* Runs if there was an error processing the form
* @param message - the error message
* @param active_form - DOM object for the form being submitted
*/
wpsl_error(message, active_form){}

/**
* Runs on form success
* @param resultcount - The number of query results
* @param results - Object containing all results
* @param active_form - DOM object for the form being submitted
*/
wpsl_success(resultcount, results, active_form){}

The above functions must be called after the simple-locator.js script has loaded. To best ensure the script has already loaded, add the simple-locator script as a dependency when enqueueing your custom Javascript file:

wp_enqueue_script(
 'your-custom-script', 
 '/path/to/your/script.js', 
 array('jquery', 'simple-locator')
 );

Settings

To access Simple Locator’s settings, choose “Simple Maps” from the “Settings” menu in the WordPress admin.

General Settings

• Google Maps API Key
  An API key is not required, but strongly encouraged. This will allow you to monitor your usage of the API and possibly prevent restriction due to being over API limits. API keys are free and available through Google’s developer console. An API is required to use the plugin’s import functionality. The importer requires a server key with the Geocode API enabled. Learn more about how to obtain a Google API key.
• Measurement Unit
  Choose between miles and kilometers. Defaults to miles.
• Custom Map Pin
  Upload a custom map pin image. The recommended image format is a transparent PNG.
• Output Simple Locator CSS
  To disable the Simple Locator CSS choose “No”.
• Include Google Maps API
  If you are using another plugin that includes the Google Maps API, it is a good idea to disable the output of the API. Setting this to “no” removes the Simple Locator generated Google Maps script tag.
• Enable Autocomplete in Search
  Enables autocomplete functionality in search inputs. The autocomplete functionality is provided by Google’s Places API. View an example of Google Places autocomplete.
• Display Map in Singular View
  By default, an embedded map is added to the content on location singular views. To remove the map, select “No”. For customized templates, disable this feature, and use the provided single map shortcode where needed.
• Location Button
  Add a “use my location” button on geolocation-enabled devices/browsers. The button will not display on devices/browsers without geolocation capabilities.
• Location Button Text
  Customize the text in the location button. A common UI element for these buttons is the “target” icon – HTML is permitted.

Post Type & Geocode Fields

Simple locator comes packaged with a “location” post type, along with the necessary fields for location search functionality (address, latitude, longitude, etc…). By default, this post type is enabled. If you’d like to use your own post type and latitude/longitude fields, you may set those here.

• Post Type for Locations
  Select the post type for location searches. For searches to work, the selected post type must have associated latitude and longitude fields, formatted in degrees.
• Latitude & Longitude Fields
  Select existing custom fields for latitude & longitude if required. Field choices are dependent on the post type selected.
• Location Post Type Name & Labels
  Customize the included “location” post type. The name and slug should be all lowercase with no spaces or special characters (they must follow the WordPress post type naming conventions). If the post type name or slug is updated after data has already been saved under that type, it will not be accessible under the new name.

Map Styles

By default, maps are displayed in standard Google Maps styling. 2 additional choices are available to add custom map styling: choose a pre-formatted style, or paste your own.

• Choose a Style
  Select the pre-formatted style for easy custom styling.
• Paste My Own Styles
  Styles must be a Javascript array, formatted to the Google Maps API V3 standards. Visit the Google Maps Style Wizard for an easy way to generate properly formatted styles. Online libraries such as snazzymaps.com are also available for choosing pre-formatted styles. When pasting the styles, include only the array, not the “styles” name.

Default Map

Sometimes you may want a map to display on page load, before the user has submitted the form. Additionally, it may be desired to have results automatically load based on the user’s location on page load (without the user submitting a form). These options may be enabled and configured under this tab.

• Show Default Map
  Enables the default map to show. The map’s location and zoom level will be saved.
• User Location
  To automatically request the user’s location, center the map at that location, and search for locations nearby, enable this option. Note: The default map must be enabled, and the user must allow access to their location manually for this to fully function. If the user does not have location services, or they deny access to their location, the default map will be shown.

Results Display

Results may be customized to include any of the chosen post type’s custom meta fields as well as post data. 

• Location Fields
  Options include the distance (will display in the chosen format – km/miles), show on map (displays a link that when clicked, scrolls to the location on the map), and all meta fields associated with the selected post type. 
• Post Data
  Includes the title, permalink, excerpt, and thumbnails. Thumbnails are selectable per size registered.
• Number or Results to Show
  To show unlimited results, set the number to -1, otherwise, set the maximum number or results to return.