Template filters written for WP Store Locator v2 still work in v3, through a backward-compatibility layer. However, the legacy helper functions are now deprecated, and several v2 settings work differently.

For example, if your wpsl_listing_template callback stops showing the phone, fax and email after upgrading to v3, it’s probably because it checks $wpsl_settings['show_contact_details']. That option was removed from the admin, so saving your settings sets it to 0.

Another example: the v2 code prints <%= distance %> without a check. When visitors search by store name there’s no distance, and every result disappears from the list.

This post covers every filter on the filters documentation page that ends in _template. For each one, you get the v2 code from the docs, the v3 version, and what changed. Copy the v3 version into your theme’s functions.php in place of the old callback.

• What changed in v3
• wpsl_listing_template
• wpsl_info_window_template
• wpsl_cpt_info_window_template
• wpsl_more_info_template
• wpsl_store_header_template
• wpsl_skip_cpt_template
• Checklist after updating your code

If you only need small changes, you may not need a filter. Since 3.0 you can edit the search results and info window HTML directly in Store Locator > Settings > Fields Manager > Section Editor.

Use the Section Editor when

• you want to add a field, move things around or change the markup, and the result is the same on every page.
• you’d rather not edit theme files. The code is saved in the database, so it keeps working if you switch themes.
• the check depends on the store’s own data, for example only showing a line when a store has a phone number. The editor supports the same <% if ( ... ) { %> checks as the filters.

Use a filter when

• the template has to change based on something PHP knows, like the current page, the logged-in user, the site language, a setting, or a value from your own code.
• you want to add translatable text with __() or esc_html__().
• you want the change in your theme or plugin code, under version control, rather than in the database.

What changed in v3

In v2, a template callback used the $wpsl and $wpsl_settings globals and a set of wpsl_*() helper functions. In v3, the same work is done through two services: template_sections builds the template parts, and wpsl_settings reads the settings.

The old functions still work, but each call logs a deprecation notice when WP_DEBUG is on.

The {{...}} tags are filled in by the plugin after your filter runs. That's why labels can be written straight into the template string. Only wpsl_label and wpsl_get_distance_unit are allowed by default; you can add your own functions with the wpsl_template_functions filter. {{wpsl_get_distance_unit()}} also respects the shortcode's distance_unit attribute, which $wpsl_settings['distance_unit'] didn't.

Contact details are now placed per location. The single "Show contact details" checkbox from v2 became a multiselect under Settings > User Experience. The values you can check for are:

Hours (ux → hours) and the location description (ux → description) use the same values. The last two options only show up when store permalinks are enabled.

Every template filter still receives the default v3 template as its first argument. For a small change, you can edit that string instead of rebuilding the whole template.

wpsl_listing_template

This filter controls the HTML of each location in the search results. The example adds a custom field called my_textinput below the address.

What changed

• Contact details: the show_contact_details check became a check for search_results in the contact details setting. $sections->contact_details() builds the block with the translated labels, and it follows the icon and “clickable contact details” settings. To change the order or add your own fields, see Customize the Contact Details.
• New in v3: the opening hours and the post content, each following its own “Location(s) of …” setting, and the “temporarily / permanently closed” notice, which is always included. The opening hours are shown below the address by default.
• Icons and buttons: the example adds the icon classes when icons are enabled, and moves the directions link into its own section when the links are styled as buttons or the “More details” link is on.
• Thumbnail: thumb only exists on some result paths in v3, so it’s guarded with typeof.
• Distance: it’s now wrapped in <span class="wpsl-distance">, which the v3 CSS styles, and guarded with typeof distance. A search by store name has no distance, and without the check every result disappears. For name searches the distance wrapper is left out completely.

wpsl_info_window_template

This filter controls the pop-up that opens when you click a marker on the store locator map. The example adds my_textinput below the address.

What changed

• Contact details: the three hand-written blocks became $sections->contact_details(). Fax is now also run through formatPhoneNumber().
• Following the settings: the contact details and the post content only show when “The store locator marker pop-up” is selected for them. The short open / closed status also needs “Show the current open / closed status?” to be on. The closed notice is always included.
• createInfoWindowActions(): now takes the store URL and permalink as well, so it can show the “More details” button. createInfoWindowActions( id ) still works, but without that button.
• Missing fields: in v3, a custom field the location doesn’t have breaks the whole pop-up. Always use the typeof check for custom fields.
• Known issue in 3.0: the plugin’s own pop-up currently also shows the store thumbnail and country. The example follows the intended design without them, so they disappear when you switch to it. This will be fixed in 3.1.

wpsl_cpt_info_window_template

This filter controls the marker pop-up on individual store pages and on maps made with the [wpsl_map] shortcode. The example adds my_textinput below the address.

What changed

• Store name: $sections->store_header( 'wpsl_map' ) links the name to the store page or store URL when one is available. Otherwise it shows the same plain strong name as v2.
• Country: it now follows the “Hide the country in the results?” setting.
• New in v3: the contact details and the post content, each shown when “The landing page marker pop-up” is selected for it. The short open / closed status needs that option for the hours, and “Show the current open / closed status?” to be on.

wpsl_more_info_template

This filter controls the “More info” link in the search results and the content that opens below it. It changed the most, because the v2 “More info” settings no longer exist.

In v2 you turned on “Show more info” and chose where the details appeared: in the store listings or in the info window. In v3 you pick a location for each type of detail instead. Contact details, hours and description each have a “The ‘more info’ section in the search results” option. The “More info” link appears when at least one of them uses it.

What changed

• One code path: the “store listings” vs. “info window” branches are gone. Details you want in the marker pop-up now go there directly, through the “The store locator marker pop-up” option, without a “More info” link.
• The old callback: the v2 “More info” location setting no longer exists in v3, so the v2 callback always takes the “info window” branch. It then prints a “More info” link that does nothing, even if you used the store listings option in v2. Replace it with the v3 version.
• When the link shows: hasMoreInfoData replaces the !_.isEmpty( phone ) || ... check. The plugin sets it to true when a field placed in “more info” has a value. It doesn’t know about your custom fields, so add those to the check yourself, as shown.
• Settings checks: !$wpsl_settings['show_contact_details'] and !$wpsl_settings['hide_hours'] became checks for more_info in the contact details and hours settings.
• Accessibility: the link now has aria-expanded, which the plugin toggles when the section opens and closes.
• When the filter runs: only when at least one detail is placed in “more info”. If none is, the “More info” link isn’t added to the template at all, so your callback never runs.
• Replacing the listing too: calling $sections->more_info_template() inside your wpsl_listing_template callback runs this filter as well, so both customizations work together.

wpsl_store_header_template

This filter controls the store name at the top of each search result and pop-up. The example keeps the default markup and adds my_textinput below the store name.

What changed

• Location argument: the filter now also passes $location: listing, info_window or wpsl_map (store pages and [wpsl_map]). Use it to change the header in only one place, for example if ( $location !== 'listing' ) { return $header_template; } at the top.
• Permalink check: on [wpsl_map] maps the permalink can be missing from the data. The typeof permalink check keeps the pop-up from breaking there.
• New window: $sections->new_window() adds target="_blank" rel="noopener" when “Open links in a new window?” is enabled. The v2 example ignored that setting.
• Class: the linked store name in the default v3 header uses class="wpsl-location-name". Keep it if you want the v3 styling for the store name to apply.
• Headings: the header sits inside a p element in every template, so don’t replace the strong with an h1–h6. To mark the name as a heading for screen readers, add a heading role instead, as shown in Use a Heading for the Store Name.

wpsl_skip_cpt_template

This filter stops the plugin from adding the map, address and opening hours to individual store pages. It’s typically used together with a custom single-wpsl_stores.php template. Nothing changes in v3; the same line still works:

add_filter( 'wpsl_skip_cpt_template', '__return_true' );

Checklist after updating your code

• Check the Section Editor. If you activated a custom List or Info window section on the settings page, the plugin uses that saved code and skips wpsl_listing_template or wpsl_info_window_template for it. Use either the Section Editor or the filter for a section, not both.

• Check where your details appear. The upgrade moves your v2 choices into the new contact details, hours and description settings under Settings > User Experience. If you used “More info” in v2, your contact details may now be set to “more info” or the marker pop-up instead of below the address.

• Guard every custom field with typeof. In v3, a field that a location doesn’t have makes that result disappear from the list, or stops the pop-up from opening. The browser console then shows “a template section failed to render” for the search results, or a ReferenceError for the pop-up.

• Turn on WP_DEBUG once. Any leftover v2 helper function logs a deprecation notice that names its v3 replacement.

• Custom fields: fields you add in the Fields Manager are included in the store locator data automatically, but not in the [wpsl_map] pop-up on store pages. Fields registered in code still need wpsl_meta_box_fields and wpsl_frontend_meta_fields. For the store page pop-up, use wpsl_cpt_info_window_meta_fields, including for Fields Manager fields.

• Clear your page cache. The plugin builds the templates on every page load, so template changes show up straight away. If you added a new field with wpsl_frontend_meta_fields, clear the cache under Store Locator > Settings > Tools > Autoload cache. A caching plugin can still serve the old version.

• Styling: if the v3 styles clash with your custom CSS, try “Disable v3 theme rules?” under Settings > Tools.