Important: WPForms “Hidden Field” is only available in WPForms Pro.
Since ASL v5.1.8, you can use a Single Line Text field instead (works in WPForms Lite/free as well).

Step 1: Add the asl_store_id Field in WPForms (Pro + Free Options)

Create a field in your WPForms form that will hold the Store ID.

Option A (WPForms Pro) — Hidden Field

• Add a Hidden Field
• Set the Field Label to: asl_store_id

Option B (WPForms Lite/Free) — Single Line Text Field (ASL v5.1.8+)

• Add a Single Line Text field
• Set the Field Label to: asl_store_id
• Open Advanced settings for that field and set CSS Classes to: asl-hidden-store-id

Optional (recommended): hide the text field using CSS (so users don’t see it):

.wpforms-field.asl-hidden-store-id {
  display: none !important;
}

Step 2: Enabling WPForms Hook in Agile Store Locator Settings

Navigate to the Agile Store Locator Settings and head to the Notification tab. Enable the WPForms hook to activate the integration between Agile Store Locator and WPForms.

Option 1: Using a Separate Lead Form

If you prefer to use a separate lead form, simply provide the store ID to the hidden “asl_store_id” field within the WPForms label. When a lead is captured through this form, the email notification will be sent directly to the store owner associated with the specified store ID.

Option 2: Including a Call-to-Action (CTA) Button in Store Locator Listing

Alternatively, you can include a Call-to-Action (CTA) button in the store locator listing. When users click on this button, it opens a form containing the WPForms integration. This form will automatically populate the “asl_store_id” field with the corresponding store ID. Upon submission, the email notification will be sent to the respective store owner, to integrate the lead form as a CTA, follow the steps below:

1- Add the WPForms ID in the shortcode as the WPForms attribute.

[ASL_STORELOCATOR wpforms="3039"]

3- Make sure that the hidden field has the CSS Classes as asl_store_id in the form.

2- Add a call to action through the Store Locator List Customization.

<a class="btn btn-asl asl-lead-cta-btn">[Contact Store]</a>

By leveraging this integration, you can streamline lead capture processes and ensure timely communication between customers and store owners.

How to include a Lead Form on the Store Detail page?

Agile Store Locator does support including a lead form that will send emails to the store of the listed page detail, Integrating a lead form with WPForms on the store detail page is a seamless process. Follow these steps to set it up:

1. Add WPForms Shortcode: On the store detail page where you want to include the lead form, insert the WPForms shortcode. This shortcode allows you to display the form on the desired page.
2. Hidden Field: Add a hidden field with the label asl_store_id in the WPForms form.
3. Enable WPForms Hook: In the ASL Settings, navigate to the Notifications tab. Locate the option to enable the WPForms hook and toggle it on. This step ensures that emails generated from the lead form submission are sent to the respective store owners.

By completing these steps, you can easily incorporate a lead form powered by WPForms into your Agile Store Locator store detail pages, facilitating seamless communication between users and store owners.

How to Check If Emails Are Being Sent

If store owners are not receiving emails, first confirm whether WordPress is sending them.

1. Install and activate WP Mail Logging
   https://wordpress.org/plugins/wp-mail-logging/
2. Submit the store contact / lead form.
3. Go to WordPress Admin → WP Mail Logging and check the latest email entry.

How to Read the Result

• Email appears in the log → WordPress sent the email successfully. Check spam folder or configure SMTP.
• Email does not appear → The email was not triggered. Verify:
  • asl_store_id field exists and is populated
  • WPForms hook is enabled in ASL Settings → Notifications
  • Correct WPForms ID is used in the shortcode

List of Store Locator Filters

How to use the above filters?

The above filters can be used in the functions.php file of your active theme, below is an example of the filter usage.

In this example, we have changed the category id to the category name, that is used in the query parameter.

/**
 * [asl_filter_locator_method description]
 * @param  [type] $attrs [description]
 * @return [type]        [description]
 */
function asl_filter_locator_method($attrs) {

	global $wpdb;

	$q_category = isset($_GET['locator-category']) && $_GET['locator-category']? $_GET['locator-category']: null;

	if($q_category) {

		$locator_category = $wpdb->get_results($wpdb->prepare("SELECT * FROM ".ASL_PREFIX."categories WHERE category_name = %s", $q_category));

		if($locator_category && isset($locator_category[0])) {

			$attrs['select_category'] = $locator_category[0]->id;
		}
	}

	return $attrs;
};

add_filter('asl_filter_locator_attrs', 'asl_filter_locator_method');

Apply your own CSS file for the Search Widget

/**
 * [asl_filter_search_widget_words_method Used this filter to change the CSS file]
 * @param  [type] $words [description]
 * @return [type]        [description]
 */
function asl_filter_search_widget_words_method($words) {

	//	Dequeue the plugin search css file
  wp_dequeue_style('agile-store-locator-asl-search');
  	
  //	Add your customized search file
  wp_enqueue_style('asl-search-widget',  get_template_directory_uri().'/asl_search-updated.css', array(), '4.9.12', 'all' );

	return $words;
}

add_filter('asl_filter_search_widget_words', 'asl_filter_search_widget_words_method');

Store Results Filter to Manipulate or Change the Store Data

/**
 * [asl_add_additional_column Use this Method to add a new field to the data]
 * @param  [type] $all_stores [description]
 * @return [type]             [description]
 */
function asl_add_additional_column($all_stores) {

  foreach($all_stores as $store) {

    $store->agent = 'John Doe';
  }

  return $all_stores;
}

add_filter('asl_filter_stores_result', 'asl_add_additional_column');

Another example of asl_filter_stores_result is to through the data from some API or custom CPT.

/**
 * [asl_add_additional_column Custom data rendered using CPT or API endpoint]
 * @param  [type] $all_stores [description]
 * @return [type]             [description]
 */
function asl_stores_custom_data($all_stores) {

	//	Array of stores
	$my_stores = [];

	//	Add the Store 1
	//$my_stores[]

	//	Add the Store 2
	//$my_stores[]

  return $my_stores;
}

add_filter('asl_filter_stores_result', 'asl_stores_custom_data');

Truncate/Delete all my existing stores data before the import process

// Delete all my stores before the import of new files, Tested with version 4.9.15
add_action('asl_before_stores_import', function() {

	//	Create an instance
	$store_inst = new \AgileStoreLocator\Admin\Store();
	
	// Must be returned as object, else it will die
	$store_inst->as_object = true;

	//	Yes, delete everything, CAN'T be restored!
	$store_inst->admin_delete_all_stores();
});

Add phone_raw on PHP Side

To use a clean phone number for tel: links, you can add a phone_raw field on the PHP side using the asl_filter_stores_result filter:

function asl_add_additional_column($all_stores) {
    foreach ($all_stores as $store) {
        $store->phone_raw = !empty($store->phone) ? preg_replace('/\D+/', '', $store->phone) : '';
    }
    return $all_stores;
}
add_filter('asl_filter_stores_result', 'asl_add_additional_column');

Now you can safely do:

{{if phone}}
<li class="sl-phone">
    <i class="icon-mobile"></i>
    <a href="tel:{{:phone_raw}}">{{:phone}}</a>
</li>
{{/if}}

Modifying the Store data on insertion/update

Using the filter below, one can easily manipulate the store data before it is being saved, in the example we have removed the https:// on the website field.

// Pre-insert store method to make modification to the data
add_filter('asl_filter_pre_insert_store', function ($form_data) {
	
	// Remove "https://"
	$form_data['website'] = str_replace("https://", "", $form_data['website']);

  return $form_data;
});

The same method as above except this time it is for update store instead of insertion.

// Pre-update store method to make modification to the data
add_filter('asl_filter_pre_update_store', function ($form_data, $store_id) {

  // Remove "https://"
	$form_data['website'] = str_replace("https://", "", $form_data['website']);

  return $form_data;

}, 10, 2);

Perform WPML Translate to the Stores Categories via WPML

The filter asl_filter_locator_categories can be utilized to translate the categories through string translation.

/**
 * [translate_asl_categories_via_wpml Translate ASL Categories via WPML]
 * @param  [type] $catgories [description]
 * @return [type]            [description]
 */
function translate_asl_categories_via_wpml($catgories) {

	//	Loop over the categories
	foreach($catgories as $sl_category) {

		//	Pass through translation string
		$sl_category->name = esc_attr__($sl_category->name,'asl_locator');
	}

	return $catgories;
};

add_filter('asl_filter_locator_categories', 'translate_asl_categories_via_wpml');

Run/Execute Shortcode in the Stores Listing

In this example, we will explain how you can execute a shortcode in the stores listing, we will use wpdatatables, which is a well-known WordPress plugin.

1. Create a custom field in the ASL Settings, and name the field table_id.
   
2. Add the table ID for the store that you want to render the table.
   
3. Add this code to your functions.php

/**
 * [asl_add_additional_column Use this Method to run a shortcode]
 * @param  [type] $all_stores [description]
 * @return [type]             [description]
 */
function asl_add_shortcode_to_listing($all_stores) {

  foreach($all_stores as $store) {
 
    if($store->table_id) {
      $store->description = $store->description.do_shortcode('[wpdatatable id='.$store->table_id.' table_view=regular]');
    }
  }
  return $all_stores;
}
add_filter('asl_filter_stores_result', 'asl_add_shortcode_to_listing');

Manipulate Content of CSV File During Import

The import process has a WordPress filter asl_parse_csv that can be used to change or manage the content at the time of import, such as you need to change the country name from US to United States from the country column, as the United States is the accepted country name from the list of countries.

/**
 * [asl_parse_csv_method Manipulate the CSV import data]
 * @param  [type] $csv [description]
 * @return [type]      [description]
 */
function asl_parse_csv_method($csv) {

	//	Get the rows
	$rows = $csv->getRows();

	//	Loop over the rows
	foreach($rows as &$row) {

		// Change the country name
		if($row[6] == 'South Africa') {
			$row[6] = 'France';
		} 
	}

	//	Put it back
	$csv->setRows($rows);

	return $csv;
}


add_filter('asl_parse_csv', 'asl_parse_csv_method');

Change the Load Stores Query via Filter

The asl_filter_stores_query_full filter allows developers to modify the query used for loading store data. This can be useful when you need to adjust the query to suit specific needs.

add_filter('asl_filter_stores_query_full', 'modify_asl_stores_query', 10, 1);

function modify_asl_stores_query($query) {
    // Replace all occurrences of 30000 with 40000 in the query
    $query = str_replace('30000', '40000', $query);

    // Return the modified query
    return $query;
}

Filter to remove unnecessary brand options from the dropdown

This filter can be used to remove brand and special options that are not present in the wp_asl_stores table. It ensures that only the relevant options are displayed in the dropdown menus.

/**
 * Filter to remove unnecessary brand options from the dropdown.
 *
 * This filter can be used to remove brand options that are not present in the `wp_asl_stores` table.
 *
 * @param array $attributes The attributes array containing the brand list.
 * @return array The filtered attributes array with only the necessary brand options.
 */
add_filter('asl_filter_locator_attributes', function ($attributes) {

    global $wpdb;

    $ASL_PREFIX = $wpdb->prefix.'asl_'; // Assuming the prefix is 'wp_asl_'

    // Step 1: Extract brand IDs
    $brand_list = $attributes['brand'];

    $brand_ids = array_map(function ($brand) {
        return $brand->id;
    }, $brand_list);

    // Step 2: Query the wp_asl_stores table to get the list of brand IDs
    $query = "SELECT brand FROM {$ASL_PREFIX}stores as s";
    $result = $wpdb->get_results($query);

    $store_brand_ids = [];
    foreach ($result as $row) {
        $store_brand_ids = array_merge($store_brand_ids, explode(',', $row->brand));
    }

    $store_brand_ids = array_unique($store_brand_ids);

    // Step 3: Filter the original brand list
    $filtered_brand_list = array_filter($brand_list, function ($brand) use ($store_brand_ids) {
        return in_array($brand->id, $store_brand_ids);
    });

    // Step 4: Update the $attributes['brand'] array
    $attributes['brand'] = $filtered_brand_list;

    return $attributes;
});

Change CSV Header Fields to Custom

Use the asl_parse_csv filter to modify CSV headers before importing into Agile Store Locator.
This is useful for mapping third-party or localized column names to ASL’s required keys.
For example, convert Straße to street, PLZ to postal_code, and Ort to city automatically during import.

/**
 * Normalize incoming CSV headers to ASL's accepted column names.
 * Converts German headers to ASL standard:
 *   - "Straße"/"Strasse" -> "street"
 *   - "PLZ"              -> "postal_code"
 *   - "Ort"              -> "city"
 *
 * Only the first row (header) is modified; data rows remain unchanged.
 */
function asl_change_header_column_fields($csv) {

	// Get all CSV rows (row 0 is the header)
	$rows = $csv->getRows();

	if (!empty($rows) && is_array($rows[0])) {

			// Map of accepted synonyms -> ASL standard header
			// Keys are lowercase for case-insensitive matching
			$header_map = array(
					'straße'  => 'street',
					'plz'     => 'postal_code',
					'ort'     => 'city',
			);

			// Loop header cells and normalize
			foreach ($rows[0] as $i => $header) {

					// Trim spaces; lower-case for matching (mb_ safe if available)
					$trimmed = trim($header);
					$key = function_exists('mb_strtolower') ? mb_strtolower($trimmed, 'UTF-8') : strtolower($trimmed);

					// If it's a known synonym, replace with ASL standard
					if (isset($header_map[$key])) {
							$rows[0][$i] = $header_map[$key];
					}
					// Else leave as-is (already standard or a different column)
			}
	}

	// Put rows back
	$csv->setRows($rows);

	return $csv;
}

// Hook into ASL CSV parsing
add_filter('asl_parse_csv', 'asl_change_header_column_fields');

Therefore, we have added the hook feature so that it will activate whenever any event occurs on the store locator, such as:

The hook can be added via the below javascript: 

<script type="text/javascript">
function asl_event_hook(_event) {
   
  if(_event.type == 'init') {
    asl_configuration.print_header = '<h3 class="custom-h3">Agile Store Locator <img src="https://agilestorelocator.com/wp-content/themes/sl-theme/images/sl-logo-dark.png"></h3>'; // example to override the configuration value
  }
}
</script>

Where should we place this event code?

The provided JavaScript snippet can be easily integrated into your store locator page using a builder like Elementor’s HTML Widget or another suitable method.

Please ensure that the code is placed on the store locator page for it to execute correctly, you can add a console statement in the code to see if it is getting executed or not.

<script type="text/javascript">
function asl_event_hook(_event) {
   
  console.log('Yes I am working just fine!', _event.type);
}
</script>

As a testing measure, you can directly insert it into the store locator view file located at the following path.

/agile-store-locator/public/partials/template-frontend-0.php

Assuming you are using Template 0. However, please note that this integration in the plugin view file will be overwritten when you update the plugin.

How to override the website button event on the listing?

In order to run your javascript when the store locator website button is clicked, you can add this method on the page. Once this function is registered on the page, it will execute instead of redirecting to that website link, it will help perform any other operations.

/**
 * [asl_website_click ASL Website button Hook]
 * @param  {[type]} store [Store Object]
 * @param  {[type]} link  [Link of the website]
 * @return {[type]}       [description]
 */
function asl_website_click(store,link) {

};

JS hook usage example:: Select the first store upon load

In this example, we have modified the script to highlight the first store on the load.

<script type="text/javascript">
function asl_event_hook(_event) {
   
  if(_event.type == 'init') {
    
    window.setTimeout(function(){

      asl_view.highlight(asl_view.stores[0]);
    
    }, 500);
  }
}
</script>

JS hook usage example:: Applying a filter for the store locator to always filter the fields

In this example, the collect is a custom field, and we have added it on “load” and “beforeclear” events, so the list will always apply that collect custom field filter.

<script type="text/javascript">
function asl_event_hook(_event) {
   
  if(_event.type == 'load' || _event.type == 'beforeclear') {
    
    asl_view.prop_filter = {type: 'collect', title: '1'};
    asl_view.refreshView();
  }
}
</script>

JS hook usage example:: Search Event data push to Google Analytics (GA4)

I assume that you have already enabled Google Analytics on your page, if not, please make sure that the GA code is added properly and the dataLayer variable is accessible, create a custom event using GA4 and push the events like the example below.

<script type="text/javascript">
function asl_event_hook(_event) {
   
  if(_event.type == 'search') {
    
    //  applied categories filters
    var active_filters = asl_view.featureFilter.array_.map(function(cat) {return cat.name_;});
    active_filters = active_filters.join(',');
    
    var first_store = asl_view.stores[0].props_.title; // in case you want to send the store title
    dataLayer.push({
      'event': 'locator_search_event', // Replace the event name
      'search_type': 'Address',
      'search_filters': active_filters,
      'address_searched': _event.data.search_text
    });
    
  gtag('event', 'locator_search', {});
  }
}
</script>

JS hook usage example:: Reset Map on Infobox Close

In this example, we have modified the script to reset the Google Maps zoom and default coordinates, make sure to have version 4.9.13 as it has improved since that version.

<script type="text/javascript">
  function asl_event_hook(_event) {
     
    if(_event.type == 'unselect') {
      
      var the_map = asl_view.getMap();
      the_map.panTo(new google.maps.LatLng(asl_configuration.default_lat, asl_configuration.default_lng));
      the_map.setZoom(parseInt(asl_configuration.zoom));
    }
  }
</script>

If you believe that there are important events missing from our system, please don’t hesitate to reach out to us. You can contact our support team via email at support@agilelogix.com. We value your feedback and are open to enhancing our offerings to better meet your needs.

JS Load Hook Example:: Pre-Select a State from the Dropdown

You will pass the state in the query parameter such as /store-locator/?select-state=NY so that will pre-select that NY state, the code below will only work when we don’t have the countries dropdown.

<script type="text/javascript">
  function asl_event_hook(_event) {

    // Get the value of a specific query parameter using jQuery
    function getQueryParam(parameterName) {
      return new URLSearchParams(window.location.search).get(parameterName);
    }

    var state_parameter = getQueryParam('select-state');
    
    if(_event.type == 'load' && state_parameter) {

      var state_to_select = state_parameter;
      jQuery('#sl-addr-ddl-state').multiselect('select', state_to_select).multiselect('refresh');
      asl_view.address_values['state'] = state_to_select;
      asl_view.refreshView();
    }
  }
</script>

JS Load Hook Example:: Pre-select values from the Address Dropdowns

In case you have enabled address dropdowns and you want to pre-select a country and it’s state, you can use the following code.

/**
   * [asl_event_hook Pre-select the Address dropdown values]
   * @param  {[type]} _event [description]
   * @return {[type]}        [description]
   */
  function asl_event_hook(_event) {
    
    if(_event.type == 'load') {
      
      (function() {

        //  Select Country US by default on the load
        var select_country  = "United States";
        this.$select = jQuery('#sl-addr-ddl-country');
        this.$select.multiselect('select', select_country).multiselect('refresh');
        asl_view._panel.address_selected.call(this);

        //  Select State CA by default on the load
        var select_state  = "CA";
        this.$select = jQuery('#sl-addr-ddl-state');
        this.$select.multiselect('select', select_state).multiselect('refresh');
        asl_view._panel.address_selected.call(this);

      })();
    }
  }

JS Set Limit Example:: Apply limit on when a search is performed

You can set a limit ONLY when a search is applied, and remove it on the clear search.

<script type="text/javascript">
  /**
   * [asl_event_hook Example of before search you can set a limit and remove it on the clear event]
   * @param  {[type]} _event [description]
   * @return {[type]}        [description]
   */
  function asl_event_hook(_event) {

    if(_event.type == 'before_search') {
      
      asl_configuration.stores_limit = 10;
    }
    else if(_event.type == 'beforeclear') {

      asl_configuration.stores_limit = null;
    }
  }
</script>

Query URL Parameter:: Change the Query Parameter of the State

With the code value, the query parameter for select-state will change based on the state dropdown selection.

<script type="text/javascript">
  
  // Function to update the query string without reloading the page
  function updateQueryStringParameter(key, value) {
      var uri = window.location.href;
      var re = new RegExp("([?&])" + key + "=.*?(&|$)", "i");
      var separator = uri.indexOf('?') !== -1 ? "&" : "?";
      if (uri.match(re)) {
          window.history.replaceState(null, null, uri.replace(re, '$1' + key + "=" + value + '$2'));
      } else {
          window.history.replaceState(null, null, uri + separator + key + "=" + value);
      }
  }

  /**
   * [asl_event_hook Example of changing the parameter via dropdown value]
   * @param  {[type]} _event [description]
   * @return {[type]}        [description]
   */
  function asl_event_hook(_event) {

    if(_event.type == 'addr_ddl_event' && _event.data.type == 'state') {
      updateQueryStringParameter('select-state', _event.data.value);
    }
  }
</script>

Clear Primary Search on Selection of Address Dropdown

This code will clear the primary search when the address dropdown option is selected.

function asl_event_hook(_event) {
    
    if(_event.type == 'addr_ddl_event' && asl_view.dest_coords) {
      asl_view._cont.find('.asl-clear-btn').trigger('click');
    } 
}

Implementing Deep Linking via Hash

As Agile Store Locator supports the deep link for the store via the hash value of the store ID, the following snippet can be used to implement it when the store is clicked.

<script type="text/javascript">
  function asl_event_hook(_event) {
     
    if(_event.type == 'select') {
      window.location.hash = '#' + _event.data.id;
    }
  }
</script>

Show an Elementor Popup on the Event of “No Stores Found”

<script type="text/javascript">
  function asl_event_hook(_event) {
     
    if(_event.type == 'no_stores') {
      if (typeof elementorProFrontend !== 'undefined' && elementorProFrontend.modules.popup) {
        elementorProFrontend.modules.popup.showPopup({ id: 'id-of-my-popup' });
      } 
    }
  }
</script>

Custom Button Events in the Listing

This event can be added by just adding a CSS Class sl-btn-custom to any button in the listing.

Show Closest Stores (No Store Found) – Manipulate Results

Event type no_stores_filter can be used to return the list of stores, this event is only fired when no stores are found for the result, and on that stage, the list of stores can be provided by applying your own custom filter, the event is released since version 4.11.6.

<script type="text/javascript">
  function asl_event_hook(_event) {

  if(_event.type == 'no_stores_filter') {

    // Prepare the list of storse
    var stores_list = Object.assign([], _event.data);

    // Sort the stores by distance
    _event.context.data_.sortDistance(_event.center, stores_list);

    //  Limit the number of stores to 5
    stores_list      = stores_list.slice(0, 5);

    // Update the list of stores
    return stores_list;
  }
};
</script>

Open Accordion Layout Node on the Page Load

Event type load when the data is loaded into the store locator, at this stage the event can be utilized to open the node by trigger click on the desired node.

<script type="text/javascript">
  function asl_event_hook(_event) {

  if(_event.type == 'load') {

   jQuery('.asl-cont #asl-list li[data-id="18"] > a').trigger('click'); // Replace 18 with the ID of the li element
  }
};
</script>

https://demosite.com/store-locator/#34 

For example, the above URL will highlight the store having ID# 34 in the store locator.

if(method_exists("\AgileStoreLocator\Helper", 'get_store')) {
	
	$a_store = \AgileStoreLocator\Helper::get_store(5);	
}

The results of the above store are as follows.

stdClass Object
(
    [id] => 5
    [title] => Bid-Bon Development
    [description] => bid bid
    [street] => 274 Kragga Kamma Road, Lorraine
    [city] => Port Elizabeth
    [state] => Eastern Cape
    [postal_code] => 23452
    [lat] => -33.96524
    [lng] => 25.50242
    [phone] => 041 888 3534
    [fax] => 
    [email] => 
    [website] => 
    [logo_id] => 1
    [path] => default.png
    [marker_id] => 1
    [description_2] => 
    [open_hours] => {"mon":"0","tue":"0","wed":"0","thu":"0","fri":"0","sat":"0","sun":"0"}
    [ordr] => 0
    [brand] => 1
    [special] => 
    [custom] => []
    [slug] => bid-bon-development-port-elizabeth
)

$clauses = [];

$limit = 100;
$offset = 0;

\AgileStoreLocator\Model\Store::get_stores($clauses, $limit, $offset);

You can pass various parameters in the $clauses array to filter the store values. The available parameters include:

• title: Filter by store title.
• description: Filter by store description.
• street: Filter by store street address.
• city: Filter by store city.
• state: Filter by store state.
• postal_code: Filter by store postal code.
• phone: Filter by store phone number.
• fax: Filter by store fax number.
• email: Filter by store email.
• is_disabled: Filter by disabled store (since version 5.1.4).

$clauses = ['city' => 'NY'];

$limit = 100;
$offset = 0;

\AgileStoreLocator\Model\Store::get_stores($clauses, $limit, $offset);

By customizing these parameters in the $clauses array, you can retrieve the desired store information programmatically.

Create Cards without PHP

If you prefer to avoid using PHP, Agile Store Locator also provides store cards that can be displayed using the [ASL_CARDS] shortcode. You can pass parameters to customize the displayed stores in a similar manner, you can follow the store cards documentation.

Create a New Store Programatically

//	Create a new store programatically
if(method_exists("\AgileStoreLocator\Admin\Store", 'add_new_store')) {

	$store_data = [
		"title" => "Bid-Bon Development",
		"description" => "bid bid",
		"street" => "274 Kragga Kamma Road, Lorraine",
		"city" => "Port Elizabeth",
		"state" => "Eastern Cape",
		"postal_code" => "23452",
		//"lat" => "-33.96524",
		//"lng" => "25.50242",
		"phone" => "041 888 3534",
	];


	//	Todo, change it
	$have_coordinates = false;
    
    // Add Business Hours (JSON accepted)
    $store_data['open_hours'] = '{"mon":["09:30 AM - 06:30 PM"],"tue":["09:30 AM - 06:30 PM"],"wed":["09:30 AM - 06:30 PM"],"thu":["09:30 AM - 06:30 PM"],"fri":["09:30 AM - 06:30 PM"],"sat":"0","sun":"0"}';    

	//	I don't have coordinates :( Let's fetch it
	if(!$have_coordinates) {

		$google_server_key = \AgileStoreLocator\Helper::get_configs('server_key');

		//	1- Get the Coordinates for the provided zipcode
		$coordinates   		= \AgileStoreLocator\Helper::getCoordinates($store_data['street'], $store_data['city'], $store_data['state'], $store_data['postal_code'], $store_data['country'], $google_server_key);

		//	Found coordinates?
		if(!empty($coordinates)) {

				$store_data['lat'] = $coordinates['lat'];
				$store_data['lng'] = $coordinates['lng'];
		}
	}

	//  Add it to request['data']
	$_REQUEST['data'] = $store_data;
    
    // Custom Fields
	$_REQUEST['asl-custom'] = ['field_name_1' => 'xyz', 'field_name_2' => 'abc'];

	//	Create an instance
	$store_inst = new \AgileStoreLocator\Admin\Store();
	
	// Must be returned as object, else it will die
	$store_inst->as_object = true;

	//	Create Store
	$response = $store_inst->add_new_store();


	echo '<pre>';
	print_r($response);
	echo '/<pre>';
	die;
}

Access All Categories

if(method_exists("\AgileStoreLocator\Model\Category", 'get_categories')) {

	$lang 			= ''; // Keep empty for default

	//	Get the Stores Categories
	$categories = \AgileStoreLocator\Model\Category::get_categories($lang);
}

To access them in parent and child hierarchy.

if(method_exists("\AgileStoreLocator\Model\Category", 'get_categories')) {

	$lang 			= ''; // Keep empty for default

	//	Get the Stores Categories
	$categories = \AgileStoreLocator\Model\Category::get_app_categories($lang);
}

Get All the Store Titles

The code below can be used to get the titles of all the stores, or any other attributes.

// Check if the 'get_stores' method exists in the Store model
if (method_exists("\AgileStoreLocator\Model\Store", 'get_stores')) {

    // Retrieve all stores using the get_stores method
    $stores = \AgileStoreLocator\Model\Store::get_stores();

    // Extract the 'title' column from the stores array and remove duplicates
    $store_titles = array_unique(array_column($stores, 'title'));

    // Initialize the dropdown HTML with a select element for store titles
    $store_dropdown = '<select id="asl-stores-title" name="store-titles">';

    // Loop through each unique store title and create an option element
    foreach ($store_titles as $title) {
        $store_dropdown .= '<option value="' . esc_attr($title) . '">' . esc_html($title) . '</option>';
    }

    // Close the select element
    $store_dropdown .= '</select>';

    // Output the complete dropdown
    echo $store_dropdown . '<br>';
} 
else {
    // Fallback message if the get_stores method does not exist
    echo 'Store data could not be loaded.';
}

Programmatically Find the Nearest Store

Agile Store Locator provides a built-in helper method that lets you fetch the closest store(s) to a given latitude and longitude directly from PHP. This is useful for custom integrations such as checkout logic, location-based routing, third-party APIs, or any workflow where you need to determine the nearest store programmatically.

Parameters

Example Usage

$lat    = 40.7128;
$lng    = -74.0060;
$radius = 25; // miles

if ( class_exists('\AgileStoreLocator\Helper') ) {

    $filters = ['categories' => 5];

    $closest = \AgileStoreLocator\Helper::get_closest_store($lat, $lng, $radius, $filters);

    if ($closest) {
        echo 'Nearest store: ' . $closest->title . ' (' . $closest->distance . ' miles away)';
    }
}

Getting Multiple Nearby Stores

If you need more than one result, simply increase the $limit:

if ( class_exists('\AgileStoreLocator\Helper') ) {

    $stores = \AgileStoreLocator\Helper::get_closest_store($lat, $lng, $radius, [], 5);

    foreach ($stores as $store) {
        echo $store->title . ' - ' . $store->distance . " miles\n";
    }
}

The returned list will be sorted automatically from nearest to farthest.

/**
* 
* Add custom Meta Tag to header. 
*/
function asl_header_meta_callback() {

	global $post;


	//	Page ID of the Store Detail
	if($post && $post->ID == '2459' && defined('ASL_PLUGIN')) {

		//	Get the Store title
		$store_title = do_shortcode('[ASL_STORE field="title"]');

		//	Have Store title?
		if($store_title) {

			$store_city = do_shortcode('[ASL_STORE field="city"]');

			echo '<meta name="store-detail" content="'.esc_attr($store_title).' in '.esc_attr($store_city).'">';
		}
	}
    
}

add_action( 'wp_head', 'asl_header_meta_callback' );

In the above code, we have hard-coded the store detail page ID, in your WordPress instance, it will be different of course, so make sure to change it, we have utilized the store field render methods.

While it may seem like a small detail. Eventually, customers will appreciate how much time and effort they are saved  (no matter how small) by directly loading the store locator with a certain parameter.

How Does it Work?

A query string (added) at the end of the store locator URL takes the customer to the store.

Furthermore, the Parameters to pre-select include:

1. Category – “category”
2. Brand – “brand”
3. Address -”addr”

The query string added at the end of the URL is: “?sl-category=x”

Where “x” represents the parameter ID ( the parameter ID can be alphabetic or numeric; depending on the parameter selected). In addition, the term “category” can be replaced with “brand” or “addr”.

For example, if a user wants to direct a customer to the store locator with “California” pre-selected as the address then the following query string is added at the end of the URL:

https://your-site.com/store-locator/?sl-addr=california

Similarly, for the categories, it will be like this, where 4 is the category to be selected on the load, multiple categories can also be passed comma separated.

https://your-site.com/store-locator/?sl-category=4

For the brand, you need to provide the brand ID as the query parameter to pre-select it.

https://your-site.com/store-locator/?sl-brand=5

For the specialty, you have to provide the specialty id as the query parameter to pre-select it.

https://your-site.com/store-locator/?sl-special=5

An example of sl-addr, the overall URL will look like this:

http://demosite.com/index.php/store-locator/?sl-addr=california

If you are looking to filter through address-related fields such as city, state, postal_code, you can refer to the document about filtering data through the shortcode attributes.

Furthermore, you might require the variables’ names that can be used in the customization. We have provided below a list of variables that can be inserted into the template.

{{:id}} {{:title}} {{:address}} {{:city}} {{:state}} {{:country}} {{:postal_code}} {{:street}} {{:open_hours}} {{:description}} {{:description_2}}
{{:dist_str}} // For the distance  
{{:c_names}}  // For the Categories 
{{:str_brand}}  // For the Brands 
{{:str_special}}  // For the Specialities 

The custom fields that are created by the “Custom Field Manager” can be used in the same way as the default variables. For example, a field called facebook_url will appear as the following:

 {{:facebook_url}}

Example 1: How to Add Store Open Days to the Store List

Users of Agile Store Locator can add the store opening days to the store list by following the below steps:

1. Go to “ASL Setting”, and head over to the “Customizer” tab
2. Select the template you are using from the “Template” drop-down menu
3. Select “list” from the “Sections” drop-down menu
4. Click on “Load Template”
5. Insert the below code into the template editor, and click on “Save Setting”

 {{if days_str}}
<li class="sl-days">
 <i class="icon-calendar"></i>
 <span class="txt-hours">{{:days_str}}</span>
</li>
{{/if}}

Once you add the above code the “store open days” (Mon, Tues, Wed, etc.) will be added to the store list.

Example 2: How to Add Store Open Days to the Infobox

Users of Agile Store Locator can add store opening days to the store infobox by following the below steps:

1. Go to “ASL Setting”, and head over to the “Customizer” tab
2. Select the template you are using from the “Template” drop-down menu
3. Select “infobox” from the “Sections” drop-down menu
4. Click on “Load Template”
5. Insert the below code into the template editor, and click on “Save Setting”

{{if open_hours}}
      <div class="pol-12">
         <div class="info-addr-inner">
            <i class="icon-clock"></i>
            <span class="txt-hours">{{:open_hours}}</span>
         </div>
      </div>
      {{/if}}
      {{if days_str}}
      <div class="pol-12">
         <div class="info-addr-inner">
            <i class="icon-calendar"></i>
            <span class="txt-hours">{{:days_str}}</span>
         </div>
      </div>
      {{/if}}

Once you add the above code the “store open days” (Mon, Tues, Wed, etc.) will be added to the store infobox.

[ASL_STORE sl-store="6"  field="address"]

The above shortcode will only render the address of the store having the store ID 6.

[ASL_STORE sl-store="7"  field="title"]

The above shortcode will only render the title of the store having the store ID 7.

[ASL_STORE field="title"]

You don’t need to provide the sl-store attribute in the shortcode if the slug is on the URL of the page.

Store Detail Map Only

To render a map only of the store detail page, specify the store map in the field attribute.

[ASL_STORE field="map"]

Similarly, you can display any default or custom field as well.

Any custom field that is created through the Custom Fields can also be displayed similarly.