When adding scripts to WordPress, you will inevitably run into a small, but painful, issue of localization. For the cool kids, localization is basically internationalization (or i18n for short).
Localizing a plugin or theme is relatively straightforward, but JavaScript presents its own difficulties since we can’t easily call the PHP functions necessary (which is one reason authors embed JavaScript in PHP files).
Since embedding JavaScript in PHP files is never a good technique, we use localization to save the day.
When using Ajax with WordPress, the JavaScript file will need to know the exact location of the WordPress site it is to interact with. You can’t hard-code this in unless you embed, so how does one get the location? Furthermore, if you display anything with JavaScript, chances are your users will want the strings to be translatable. I’ll show you in a later chapter how to allow translations for your strings without having to do the localization step.
Fortunately, WordPress provides the ultra-handy wp_localize_script
function.
The wp_localize_script
function takes in three arguments:
The handle argument will be the same handle you use for your script name when using wp_enqueue_script
.
For example, if you have a handle of my_script
, you would use the same name when calling the wp_localize_script
function.
The object_name argument is a string that tells WordPress to create a JavaScript object using the name you specify.
It’s important that the string you pass is as unique as possible in order to minimize naming conflicts with other scripts.
For the upcoming example, our object name will be swpajaxp
.
The l10n argument is an array of strings you would like to localize.
Within this array, you create an array key and an array value. The array key will be what you reference in your JavaScript file, so please keep it short (and no spaces or funky characters!).
Say, for example, we have enqueued a script with the handle: sample_wpajax_plugin
. Let’s also make up an object name that we can use in JavaScript. Let’s use swpajaxp
(short for Sample WP Ajax Plugin). Then, we have to decide what to pass as an array. In the example below, let’s choose a PHP version and a URL to WordPress’ admin-ajax
file (I’ll go over admin-ajax
in a separate chapter).
If we re-use the code I went over in Chapter 4, which you can find at https://github.com/wpajax, it’ll look something like this:
wp_enqueue_script( 'sample_wpajax_plugin', SAMPLE_WPAJAX_URL . '/js/init.js', array( 'jquery' ), SAMPLE_WPAJAX_VERSION, true ); wp_localize_script( 'sample_wpajax_plugin', 'swpajaxp', array( 'phpversion' => PHP_VERSION, 'ajaxurl' => admin_url( 'admin-ajax.php' ), ) );
Now in our JavaScript file, we can access the swpajaxp
JavaScript object because wp_localize_script
outputs the necessary object and variables before our script is loaded. We can then get some variables that are essentially being passed from the backend.
Let’s modify our init.js
file and output these to the console. For reference, here’s what’s currently in our init.js
file from Chapter 4, which is just a simple “Hello World.”
jQuery(function($) { console.log('Hello World'); });
Let’s modify this to output our new variables to the console. Here’s what the code would look like:
jQuery(function($) { console.log('Hello World'); console.log(swpajaxp.phpversion); console.log(swpajaxp.ajaxurl); });
See how we’re just accessing the swpajaxp
object and referencing its members using dot notation? It’s as simple as that.
Here’s what you should expect to see in your developer console:
It should output the current PHP version you are running and a path to WordPress’ admin-ajax
file (more on that later I promise).
And it’s as simple as that. You can view the completed code at https://github.com/wpajax/chapter-5. Try playing with adding more variables to wp_localize_script
and outputting them to the console.
The wp_localize_script
function is useful for getting PHP functionality to show up on the front-end and its great for internationalization, which I’ll go over in a later chapter. In the next chapter, we’ll take a break from JavaScript (be thankful) and I’ll show you how to load CSS properly so you can slowly begin building your Ajax-based app and make it look pretty.