How to Apply Javascript Hooks

Some users may require “hooks” to record certain activities on the store locator. For example, a user may need hooks for directions, Icons, lists, Items, searches, navigation, etc. Furthermore, hooks are a very useful tool that will make your store locator more versatile.

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

Event Type	Description
init	When the store locator is initialized.
load	When the store locator data is loaded.
search	When a search is performed
clear	When the address search is cleared (since version 4.8.20)
beforeclear	When the address search is cleared but before the list is recompiled (since version 4.8.20)
select	When the store is selected (since version 4.8.20)
unselect	When the store is unselected (since version 4.8.20)
direction	When the “direction” button is clicked.
geolocation	When the geolocation is performed.
no_stores	When no stores are found in the search.
pickup	When the pickup button is selected during the WooCommerce checkout
category	When the category filter is applied.
addr_ddl_event	When the address dropdown value is changed (since version 4.10.1)
before_search	Before a search is started (since version 4.9.16)
custom_btn	Any button in the listing template having CSS class “sl-btn-custom” can be used to achieve custom events (since 4.10.5)

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>

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.

<script type="text/javascript">
  function asl_event_hook(_event) {
     
    if(_event.type == 'custom_btn') {
      var clicked_store = _event.data.store;
      // When the button is clicked, the store object can be used in various ways! 
    }
  }
</script>