Wp Ajax – WordPress Hook to Handle Ajax Request

wp_ajax is not a hook or callback, rather it is just a prefix of WordPress Actions, what is called when a browser or web-client request with an action query variable to wp-admin/admin-ajax.php.

So wp-admin/admin-ajax.php?action=contact-us will fire wp_ajax_contact-us Action Hook. – Here you can see the action is fired by appending wp_ajax to the requested ‘action’ query parameter value ‘contact-us’.

In short, it is 'wp_ajax_' . $_REQUEST['action'].

How to use the action hook ?

As like other WP Action hook, simply hook with a function.

Example: add_action( 'wp_ajax_contact-us', 'contact_us_requested' );.

Explanation: Here contact_us_requested is a function you can use to do some process or to send some out put to the browser. You can replace the function hooked to the action contact_us_requested to any function you need.

Why request to wp-admin/admin-ajax.php file ?

Because, wp-admin/admin-ajax.php do the process and enable the callback after loading all of WordPress core files, variables to make the action available for you. So if you hook to the action from themes function.php or from a plugin, both will work fine.

What is wp_ajax_nopriv ?

Well, if you are a WordPress developer, you can say i have said wrong here before. Cause, wp_ajax prefix is not always used, therefore wp_ajax_nopriv is used. wp_ajax_nopriv does the same thing as wp_ajax prefix does, unless it only fires when user is not logged in.

Not logged in user – 'wp_ajax_nopriv_' . $_REQUEST['action']
Logged in users – 'wp_ajax_' . $_REQUEST['action']

How to make WordPress Ajax call both for logged in and not logged in User ?

Just Simple. Hook to both wp_ajax and wp_ajax_nopriv prefix together.

Example:

add_action( 'wp_ajax_contact-us', 'contact_us_requested' );
add_action( 'wp_ajax_nopriv_contact-us', 'contact_us_requested' );

Note: wp_ajax and wp_ajax_nopriv both will not be fired at once, so your function will be called only once not twice. — for further assistance, you could explore admin-ajax.php file inside wp-admin directory for reference.

What is WordPress ‘ajaxurl’

ajaxurl is a JavaScript variable used in WP to pass Ajax requests to that uri. Usually it is wp-admin/admin-ajax.php. WordPress automatically include this variable on every page within wp-admin area, but not on the front pages ex: post/page/category/author/search/tag etc.

How to add ‘ajaxurl’ to WordPress site Front pages ?

Including the following line of codes on your theme/plugin file will enable ajaxurl variable.

function add_ajaxurl_cdata_to_front(){ ?>
	<script type="text/javascript"> //<![CDATA[
		ajaxurl = '<?php echo admin_url( 'admin-ajax.php'); ?>';
	//]]> </script>
<?php }
add_action( 'wp_head', 'add_ajaxurl_cdata_to_front', 1);

Tutorial – Using Ajax in WordPress

Here i Will show you a basic tutorial to use an ajax call. In this tutorial, We will Show Site Description upon clicking on an Anchor.

First, Add an anchor with a unique id ( content are ex: sidebar, content, footer etc or hardcode in theme template files ).

Anchor to be placed:

<a id="view_site_description" href="javascript:void(0);">View Our Site Description</a>

Now We have a link/anchor on our page with view_site_description id property.

- The javascript codes.

function add_js_to_wp_footer(){ ?>
	<script type="text/javascript">
	jQuery('#view_site_description').click(function(){
		jQuery.ajax({
			type: 'POST',
			url: ajaxurl,
			data: {"action": "view_site_description"},
			success: function(data){alert(data);}
		});
	return false;
	});
	</script>
<?php }
add_action( 'wp_footer', 'add_js_to_wp_footer' );

Add this to your themes functions.php or a plugin file.

Explanation: In the above code, we have called an OnClick event. Whenever, an element having id ‘view_site_description’ is clicked, jQuery will Send a HTTP POST request to the ajaxurl ( wp-admin/admin-ajax.php file ) with a query string action=view_site_description. and the return value will be shown as an JavaScript alert.

As We have discussed before, that an action query variable request(post/get) to wp-admin/admin-ajax.php file fire an action hook, though clicking on the link will produce a wp_ajax_view_site_description or wp_ajax_nopriv_view_site_description hook available as we are posting with view_site_description as parameter ‘action’ value..

Lets create a function to process the ajax request and display our site description.

function view_site_description(){
	echo get_bloginfo( 'description', 'display' );
	die();
}
add_action( 'wp_ajax_view_site_description', 'view_site_description' );
add_action( 'wp_ajax_nopriv_view_site_description', 'view_site_description' );

Add this to your themes functions.php or a plugin file.

Now if everything is OK and placed as described, clicking on the link will alert you with your site description.

Notice: You site/theme must call jQuery Library before crawling our jQury code, unless request will not work. if jQuery isn’t initialized or not implemented on your WordPress site, place the following code on your themes functions.php file.

function load_jquery_core(){
	wp_enqueue_script( 'jquery' );
}
add_action( 'wp_enqueue_scripts', 'load_jquery_core');

This article will be continued describing how you can produce error or success upload sending Ajax request on your WordPress Site.