Javascript API

The javascript API consists of two parts, one is the events triggered by the plugin, and methods, which you can use to trigger specific events.

Events list

The events are fired on the main search container element which you can target with ".asp_main_container" class selector. For example attaching an event handler before the search starts:

// Native javascript (ES6)
document.querySelectorAll(".asp_main_container").forEach(function(el){
  el.addEventListener("asp_search_start", function(event) { 
    // event.detail carries the arguments
    const [id, instance, phrase] = event.detail;
    console.log(id, instance, phrase); 
  });
});

// With jQuery
$(".asp_main_container").on("asp_search_start", function(event, id, instance, phrase) { 
  console.log(id, instance, phrase); 
});

Common arguments

All of the events will always pass on these three arguments (+ additional if defined):

  • event (object) - a common javascript event object, always passed in event handlers

  • id (integer) - the search ID. This is the same as the one in the shortcode.

  • instance (integer) - the instance number of the current search ID. This will help if the same search shortcode is used multiple times on the same page.

When using native javascript, the event arguments can be found in the event handlers argument, in the event.detail array. See the example above.

Triggers when the search search instance is initialized.

asp_settings_show

Triggers when the search settings are displayed.

asp_settings_hide

Triggers when the search settings get hidden.

asp_results_show

Triggers when the search results are displayed.

asp_results_hide

Triggers when the search results get hidden.

asp_elementor_results

Triggers when the search settings are displayed.

Additional arguments

  • element (Element) - The node object

asp_search_start

Triggers right before the search is started.

Additional arguments

  • s (string) - The search phrase

asp_search_end

Triggers right after the search is finished.

Additional arguments

  • s (string) - The search phrase

  • data (string) - HTML data returned by the server

Sample implementation to the functions.php file in theme/child theme directory

// Using Native Javascript (ES6)
add_action('wp_footer', 'asp_api_sample_code');
function asp_api_sample_code() {
	?>
	<script>
	jQuery(function($){
		document.querySelectorAll(".asp_main_container").forEach(function(el){
		  el.addEventListener("asp_search_end", function(event) { 
		    // event.detail carries the arguments
		    const [id, instance, phrase] = event.detail;
		    console.log(id, instance, phrase); 
		  });
		});
	});
	</script>
	<?php
}

// Using jQuery
add_action('wp_footer', 'asp_api_sample_code');
function asp_api_sample_code() {
	?>
	<script>
	jQuery(function($){
		$(".asp_main_container").on("asp_search_end", function(){
			console.log(id, instance, phrase); 
		});
	});
	</script>
	<?php
}

Triggering Events/Functions

To call a pre-defined event, use either version of the following function:

ASP.api( id, function_name);
ASP.api( id, instance, function_name);
ASP.api( id, function_name, args);
ASP.api( id, instance, function_name, args);

Function arguments

  • id (integer) - the search ID. This is the same as the one in the shortcode. If id=0, then the call applies to all visible search instances on the page.

  • instance (integer) - the instance number of the current search ID. This will help if the same search shortcode is used multiple times on the same page.

  • function_name - the event/function you want to trigger

  • args - arguments passed to the triggered function

Functions list

searchFor

Triggers the search for a specific search phrase.

Arguments

  • s (string) - the search phrase

Examples

// On all instances on search ID=1
ASP.api(1, "searchFor", "search phrase");

// On instance 2 of search ID=1
ASP.api(1, 2, "searchFor", "search phrase");

searchRedirect

Triggers the search redirection to the results page (as configured on the back-end) using the given search phrase.

Arguments

  • s (string) - the search phrase

Examples

// On all instances on search ID=1
ASP.api(1, "searchRedirect", "search phrase");

// On instance 2 of search ID=1
ASP.api(1, 2, "searchRedirect", "search phrase");

toggleSettings

Toggles the search settings container state to either visible or invisible.

Arguments

  • state (string) - 'show' or 'hide'

Examples

// On all instances on search ID=1
ASP.api(1, "toggleSettings", "opened");

// On instance 2 of search ID=1
ASP.api(1, 2, "toggleSettings", "closed");

closeResults

Closes the results box

Arguments

  • clear (bool) - Clears the search input, when true. Defaults to false.

Examples

// On all instances on search ID=1
ASP.api(1, "closeResults");
// On instance 2 of search ID=1, also clears the search input
ASP.api(1, 2, "closeResults", true);

getStateURL

Returns a URL for the currently viewed page, with the search settings preset to the current state. Visiting this URL will preset the search settings to that state.

You can learn more about this function here.

Examples

// On instance 2 of search ID=1 - the instance 
ASP.api(1, 2, "closeResults", true);

Examples

Search for a specific phrase on search ID 1:

ASP.api(1, "searchFor", "search phrase");

Similarly, but only on instance 1:

ASP.api(1, 1, "searchFor", "search phrase");

Search all visible instances:

ASP.api(0, "searchFor", "search phrase");

Settings

Toggle search settings box on/off:

ASP.api(1, "toggleSettings");

// ..or specific instance with the same search ID only
ASP.api(1, 2, "toggleSettings");

Explicitly show/hide the settings:

// show
ASP.api(1, "toggleSettings", "show");

// hide
ASP.api(1, "toggleSettings", "hide");

// show-hide setting of all visible instances
ASP.api(0, "toggleSettings", "show");
ASP.api(0, "toggleSettings", "hide");

Results

To hide the results window:

ASP.api(1, "closeResults");

// close all open result boxes
ASP.api(0, "closeResults");

// ..or specific instance with the same search ID only
ASP.api(1, 2, "closeResults");

Current search state URL - presetting the search filters and input to a specific state

There is a way to get the current filters and search input state on the current page, and generate a URL - which presets the search to this state.

// Get the current state of the search filters on search ID=1, and first printed instance
ASP.api(1, 1, 'getStateURL')

This returns a string like:

https://yoursite.com/?p_asid=1&p_asp_data=1&current_page_id=1041&woo_currency=USD&qtranslate_lang=0&filters_changed=0&filters_initial=1&termset%5Bcategory%5D%5B%5D=81&termset%5Bcategory%5D%5B%5D=82&termset%5Bcategory%5D%5B%5D=83&termset%5Bcategory%5D%5B%5D=98&termset%5Bcategory%5D%5B%5D=147&termset%5Bcategory%5D%5B%5D=103&termset%5Bcategory%5D%5B%5D=102&termset%5Bcategory%5D%5B%5D=100&termset%5Bcategory%5D%5B%5D=84&termset%5Bcategory%5D%5B%5D=92&termset%5Bcategory%5D%5B%5D=95&termset%5Bcategory%5D%5B%5D=94&termset%5Bcategory%5D%5B%5D=93&termset%5Bcategory%5D%5B%5D=96&termset%5Bcategory%5D%5B%5D=86&termset%5Bcategory%5D%5B%5D=87&termset%5Bcategory%5D%5B%5D=85&asp_gen%5B%5D=title&asp_gen%5B%5D=content&asp_gen%5B%5D=excerpt&post_date_from_real=31-01-2011&post_date_from=2011-01-31&post_date_to_real=23-12-2020&post_date_to=2020-12-23&customset%5B%5D=post&customset%5B%5D=page"

..visiting this URL will preset the search filters to this state.

Last updated

Copyright Ernest Marcinko