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.
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"]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' );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);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.
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” |
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.
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')
);
To access Simple Locator’s settings, choose “Simple Maps” from the “Settings” menu in the WordPress admin.
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.
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.
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.
Results may be customized to include any of the chosen post type’s custom meta fields as well as post data.