Using wp_localize_script in WordPress

Written by - Published on

I’ve recently used wp_localize_script() in WordPress and thought it would be a good thing to share so that if you’re not familiar with it (some of you may be), you can start using it straight away!

So what exactly is this function and what does it do? (if you’re only here for the good stuff, you can skip to the how to)

A short introduction?

A brief introduction to the wp_localize_script() plugin. You can read the ‘official’ description on the WordPress codex as always. To quote the codex:

Localizes a registered script with data for a JavaScript variable.

This lets you offer properly localized translations of any strings used in your script. This is necessary because WordPress currently only offers a localization API in PHP, not directly in JavaScript…

Though localization is the primary use, it can be used to make any data available to your script that you can normally only get from the server side of WordPress.

So what does that actually mean? Good question. Essentially, using this function allows us to use PHP variables in a javascript file. We can basically set a few variables in PHP, use the function to pass across to our javascript file and use however we like.

If you haven’t heard of this before, you’re probably thinking, why have I not! I thought exactly the same thing when I first started using it. I’ve used it when using Ajax in WordPress. You can set a PHP variable for admin-ajax.php URL and pass this into your javascript file to use, rather than having to hard-code it in for example.

How do we use it?

We need to actually have an active script on the website before we can use the function. This isn’t a hard-coded link in your theme’s header.php either, we’re going to be using the wp_enqueue_script (follow the link to read more about this) function.

In this example, we’ll imagine we are using some Ajax in our javascript file, maybe to load some posts onto a page on the fly. First of all, you’ll have a plugin set up or be doing this in your theme’s functions.php. You’ll want to enqueue a script like this:


function add_our_script() {

wp_register_script( 'ajax-js', get_template_directory_uri() . '/js/ajax.js', array( 'jquery' ), '', true );
wp_enqueue_script( 'ajax-js' );

}
add_action( 'wp_enqueue_scripts', 'add_our_script' );

So now we have sourced our ajax script file, within that file we can write all of our code which is going to grab our posts and display them on the page. One of the biggest hurdles is how to pass our parameters through to WordPress’s ajax handler file. There are probably hundreds of ways of doing this, but here is how you can do it using wp_localize_script.

In your javascript file, you’ll have something like this:


jQuery(document).ready(function($) {

    var ajax_url = '/wp-admin/admin-ajax.php';
	var data = {
		'action': 'my_action',
		'whatever': 1234
	};

	$.post(ajax_url, data, function(response) {
		alert(response);
	});
});

This is just a very simple example which I got off of the WordPress codex, but it’s a good demonstration of what we’re after. So you’ll see that ajax_url is defined as a static URL. This isn’t good practice for a lot of reasons and wp_localize_script can help us out here.

By editing our add_our_script function, we can make the LIVE admin-ajax.php URL used by WordPress accessible in our javascript, without the need for any hard-coding. This is how we’d do it:


function add_our_script() {

wp_register_script( 'ajax-js', get_template_directory_uri() . '/js/ajax.js', array( 'jquery' ), '', true );
wp_localize_script( 'ajax-js', 'ajax_params', array( 'ajax_url' => admin_url( 'admin-ajax.php' ) ) );
wp_enqueue_script( 'ajax-js' );

}
add_action( 'wp_enqueue_scripts', 'add_our_script' );

So by adding the wp_localize_script function we can set some paramaters to make availaable to our javascript file. The format is as follow:


wp_localize_script( $handle, $name, $data );
  • $handle in our case the the script we want to ‘attach’ these parameters to.
  • $name is going to be the name of the variable that we can access in our javascript file (this is a javascript object name, so can’t contain dashes. Use underscores or camelCasing).
  • $data is the data itself

Bearing that in mind, this is how we use the function:

wp_localize_script( 'ajax-js', 'ajax_params', array( 'ajax_url' => admin_url( 'admin-ajax.php' ) ) );

Now, in our javascript file, we can source the admin-ajax.php file using the correct function in PHP. The same javascript function now becomes:


jQuery(document).ready(function($) {

    var ajax_url = ajax_params.ajax_url; // so we access our ajax_url through the ajax_params object
	var data = {
		'action': 'my_action',
		'whatever': 1234
	};

	$.post(ajax_url, data, function(response) {
		alert(response);
	});
});

To see this in action and put it into practice, check out this tutorial about how to use Ajax & WP_Query

This function is in no way restrained for use with just Ajax, you can literally pass anything through you want — whether that be a message, page id, page title and so on. Now that you know about the function, you can use it as you wish!

I hope this has been useful and some of you can start to use this, any questions or comments please post below!