# 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:

```javascript
window.addEventListener("load", () => {
	document.querySelectorAll(".asp_main_container").forEach((el) => {
		el.addEventListener("asp_search_end", (event) => {
			// event.detail carries the arguments
			const [id, instance, phrase] = event.detail;
			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.

{% hint style="warning" %}
When using native javascript, the event arguments can be found in the event handlers argument, in the **event.detail** array. See the example above.
{% endhint %}

### asp\_init\_search\_bar

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

```php
add_action('wp_footer', function () {
	?>
	<script>
		window.addEventListener("load", () => {
			document.querySelectorAll(".asp_main_container").forEach((el) => {
				el.addEventListener("asp_search_end", (event) => {
					// event.detail carries the arguments
					const [id, instance, phrase] = event.detail;
					console.log(id, instance, phrase);
				});
			});
		});
	</script>
	<?php
});
```

## Triggering Events/Functions

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

```javascript
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

```javascript
// 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

```javascript
// 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

```javascript
// 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

```javascript
// 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](https://knowledgebase.ajaxsearchpro.com/miscellaneous/other/presetting-search-options-via-a-custom-url).

#### Examples

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

### Examples

#### Search

Search for a specific phrase on search ID 1:

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

Similarly, but only on instance 1:

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

Search all visible instances:

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

#### Settings

Toggle search settings box on/off:

```javascript
ASP.api(1, "toggleSettings");

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

Explicitly show/hide the settings:

```javascript
// 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:

```javascript
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.

```javascript
// 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.