Codex

AJAX in Plugins

Languages: English • 日本語 • (Add your language)

Contents

Introduction

This article, aimed at plugin developers, describes how to add Ajax to a plugin. Before reading this article, you should be familiar with the following:

  • Ajax - Overview of the technology
  • Writing a Plugin - How to write a plugin
  • Plugin API - Filters and actions - what they are and how to use them
  • How to add HTML to the appropriate WordPress page, post, or screen -- for instance, if you want to add Ajax to administration screens you create, you will need to understand how to add administration menus to WordPress; if you want to add Ajax to the display of a single post, you'll need to figure out the right filters and actions to add HTML to that spot on viewer-facing blog screens. This article does not cover these topics.

Error Return Values

If the AJAX request fails when the request url is wp-admin/admin-ajax.php, it will return either -1 or 0 depending on the reason it failed. Additionally, if an AJAX request succeeds, it will return a 0.

Ajax on the Administration Side

Since Ajax is already built into the core WordPress administration screens, adding more administration-side Ajax functionality to your plugin is fairly straightforward, and this section describes how to do it.

Here's a short example. All this will be in one file.

First, add some javascript that will trigger the AJAX request: 

<?php
add_action('admin_head', 'my_action_javascript');

function my_action_javascript() {
?>
<script type="text/javascript" >
jQuery(document).ready(function($) {

	var data = {
		action: 'my_action',
		whatever: 1234
	};

	// since 2.8 ajaxurl is always defined in the admin header and points to admin-ajax.php
	jQuery.post(ajaxurl, data, function(response) {
		alert('Got this from the server: ' + response);
	});
});
</script>
<?php
}


Then, set up a PHP function that will handle that request: 

<?php 

add_action('wp_ajax_my_action', 'my_action_callback');

function my_action_callback() {
	global $wpdb; // this is how you get access to the database

	$whatever = intval( $_POST['whatever'] );

	$whatever += 10;

        echo $whatever;

	die(); // this is required to return a proper result
}

That's it! You will need to add a few details, such as error checking and verifying that the request came from the right place ( using check_ajax_referer() ), but hopefully the example above will be enough to get you started on your own administration-side Ajax plugin.

NOTE: Since Version 2.8, The javascript global variable ajaxurl can be used in case you want to separate your javascript code from php files into javascript only files. This is true on the administration side only.

Ajax on the Viewer-Facing Side

As of WordPress 2.8, there is a new hook similar to 'wp_ajax_my_action':

  • 'wp_ajax_nopriv_my_action' executes for users that are not logged in.

So, if you want it to fire for both visitors and logged-in users, you can do this: 

add_action('wp_ajax_my_action', 'my_action_callback');
add_action('wp_ajax_nopriv_my_action', 'my_action_callback');

Note: Unlike on the admin side, the ajaxurl javascript global does not get automatically defined for you - unless you have BuddyPress installed. If installed, BuddyPress sets the ajaxurl global to site_url( 'wp-load.php' ) for its own purposes. So instead of relying on a global JavaScript variable, use the tip suggested in the article 5 tips for using AJAX in WordPress and declare a JavaScript namespace object with its own property, ajaxurl. As the article suggests, use wp_localize_script() to make the URL available to your script, and generate it using this expression: admin_url('admin-ajax.php')

Note 2: When selectively loading/hooking your AJAX scripts for front-end/back-end loading only and using the is_admin() function, your wp_ajax and wp_ajax_nopriv hooks MUST be inside the is_admin() === true part. 

<?php
if( is_admin() )
{
    add_action('wp_ajax_handle_frontend_ajax', 'handle_frontend_ajax_callback');
    add_action('wp_ajax_admin_only_ajax', 'admin_only_ajax_callback');
    
    // Load "admin-only" scripts here
}
else
{
    // Do front-end loading here
}

The front-end ajax scripts would be using the handle_frontend_ajax action even though it is in the is_admin() function.


Further Reading - External Resources

Related References

Retrieved from "http://codex.wordpress.org/AJAX_in_Plugins"

Codex Resources