Loading

Simple Locatorfor Wordpress

Try it: Search for a Coffee Shop

©2017. Kyle Phillips. Crafted with pride in WordPress
Download

hero-pinEasy-to-Use Location Search for WordPress Simple enough for plug and play, flexible enough for a customized location search solution.

Learn More

Features

Location Search for any Post Type

Use Existing Content

Optionally set your own post type and latitude/longitude fields. This is ideal for developers who need a way to provide location search with existing data.

  • Choose any existing post type to search.
  • Choose existing latitude and longitude fields.
Set Your Own Location Content Sources

Included Post Type & Fields

Preconfigured “Location” post type comes packaged with required fields.

  • Ideal for an “out-of-the-box” location search solution.
  • Address automatically geocoded on save, using Google Maps’ geocoding API.
Included location post type with geocoded fields

Customized Maps

Choose from an included list of map styles, or use your own custom styles.

  • Includes a wide variety of pre-configured styles to choose from.
  • Developer friendly – use your own Google Maps API formatted style array for full customization over the appearance of your maps.
  • Option to upload a custom map marker (pin).
  • Additional customization options available using shortcode parameters.
Customizable maps

Developer-Friendly

  • JavaScript Callbacks

    Simple Locator includes a series of JavaScript callback functions, enabling you to easily customize your map’s functionality and display. 

  • Use any Post Type

    Already have a post type with latitude and longitude fields? Unlike other store locator plugins, Simple Locator allows you to specify your own data sources.

  • Embedded Forms

    Easily embed and customize search forms using the Simple Locator widget or shortcode. 

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:

Option Type Use Example
distances A comma separated list of numbers Customize the list of available distances to choose from in the form distances=”5,10,20,50”
mapheight Integer The map height in pixels mapheight=”250″
mapcontainer Unique ID for DOM element Optional custom map container (Must have a unique ID attribute) mapcontainer=”#mapdiv”
resultscontainer Unique ID for DOM element Optional results container (Must have a unique ID attribute) resultscontainer=”#results”
buttontext String Text to display in submit button (can contain HTML) buttontext=”Submit”
addresslabel String Customize the address form label addresslabel=”Zip Code or City”
mapcontrols show / hide Hide or show the map controls mapcontrols=”hide”
mapcontrolsposition String Where to display the map controls. See the Google Maps API documentation for options mapcontrolsposition=”TOP_LEFT”
placeholder String Customize the search input placeholder text placeholder=”Enter Location”
ajax true/false Disable AJAX form submission (defaults to true – NOTE: custom map/results containers not available on non-AJAX forms) ajax=”false”
perpage Integer Number of results to display per page on non-AJAX forms (not available on AJAX forms) perpage=”20″
noresultstext String Customize the text that displays if no results are returned noresultstext=”No Results Found”
showgeobutton true/false Show/Hide the geolocation button (also configurable in the plugins settings) showgeobutton=”true”
taxonomies A comma separated list of taxonomy names Add taxonomy dropdown fields to the search form. Filters search results by taxonomy. Available on AJAX forms only. taxonomies=”category,post_tag”

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"]
Option Type Use Example
post Post ID (Integer) If no post ID is provided, the shortcode will use the current template’s post ID. post=”1″
additionalfields hide/show If the built-in “locations” post type is being used, show or hide the additional fields. Fields are hidden by default. additionalfields=”show”

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.

FAQs

  • Will this run on any WordPress site?

    Simple locator requires a minimum of PHP version 5.3.2, and will not install if this minimum requirement is not met. If you are unsure what version of PHP your server is running, contact your hosting provider.

  • What 3rd party services does this plugin use?

    All geocoding and mapping functionality takes advantage of the Google Maps Javascript API V3. Unexpected changes in the API service may effect plugin functionality, but any changes will be monitored and addressed as needed.

  • Can I hide the map, and only show text results?

    Use of the Google Maps API requires that the data be displayed in a Google map. Hiding the map violates the API licensing.

  • How do I add custom functionality to the generated maps?

    Several Javascript callback functions are provided for key events in search, and map rendering. For example, hooking into the wpsl_googlemaps_response function provides a full Google Maps response object with the geocoded location. The wpsl_click_marker function provides a way to add custom functionality to marker click events. An example of this is used in the example form in the sidebar. Clicking a map marker causes the results to scroll and highlight the chosen marker. Need to show a custom error message if no results are returned? Hook into the wpsl_no_results function. 

  • Is my existing data automatically geocoded?

    No. If an existing post type is chosen as the search term, there must be preformatted latitude and longitude fields associated with each post. All new posts under the “location” post type are geocoded on save.

  • I need custom functionality, how do I get it?

    Use the contact form on this page to submit a request. If the functionality makes sense to include in the core plugin, we’ll place it on a list for future release development. If not, we may be able to provide some guidance on how to achieve what you’re trying to accomplish. Simple Locator has a powerful API with filters for just about everything, including SQL queries.

  • Does it work outside the United States?

    Absolutely. The search form uses the Google Maps API geocoding service, which offers reliable data throughout the world. Localization is possible using the provided POT files in the /languages folder.

  • Will this work on my non-SSL enabled site?

    Maybe. Google recently updated the geolocation capabilities within chrome to only work on SSL enabled sites. If you’re using the “Use My Location” button included with the plugin, you will need SSL on your site. You will also need a verified SSL site to use the CSV importer. 

  • Can I use multiple post types?

    No. Simple locator allows you to set one post type for locations. This can be the included post type, or your own, but multiple post types are not supported.

  • Why does it take so long to import locations?

    Google throttles their geocoding services to 5 requests per second. 

  • How do I get my form and map to look/work like yours?

    Simple locator is designed to be have as much flexibility as possible. The included styles are very minimal, with the idea that you’ll make it your own. It is recommended to add custom styles to your theme to fit its look and feel. There are plenty of Javascript callbacks available to add custom functionality as well.

  • I need a special feature and I want to pay you for it.

    I am not available for contract or for-hire work. 

  • Will this plugin work for [insert special case here]?

    I would recommend downloading and installing the plugin and testing. 

Support

Before submitting a form, please review the frequently asked questions above.