One of the great reasons to love WordPress is the number of programming tasks it makes easy. Today we’ll look at perhaps my favorite bit of WordPress magic:
As the name doesn’t imply,
wp_localize_script() is Great
I’m writing a (bare-bones but functional) plugin that creates keyboard shortcuts for the WordPress post editing experience. With this plugin, for example, you can hit
ctrl+s on your keyboard and it’ll “Save Draft” on your current post—without you needing to move your mouse up to the “Save Draft” button.
We Need PHP to Manage Site Options
Here’s the thing: I want the keyboard shortcuts to be user-configurable. If you, the user, want “Save Draft” to map to
ctrl+d instead, I want that to be possible.
This means that every shortcut binding (“
ctrl+d binds to ‘Save Draft'”) needs to be saved as a site option: a piece of data to be stored in WordPress’s database, and both accessed and changed in PHP using WordPress’s useful but tangled Settings API.
ctrl+s—or whatever custom shortcut—in a post editor page in her browser. We also need JS to take the appropriate action: trigger the page’s “Save Draft” process as if “Save Draft” itself had been clicked.
We Need Shared Variables Across Both Environments
To sum up:
- PHP needs to manage a site option: a server-side variable that stores the user’s custom “Save Draft” keyboard shortcut across the site.
Hacky solutions involve manipulating the page’s markup or DOM.
There are a few ways to solve the problem we just outlined. Maybe
wp-admin/post.php gets an invisible
<div> in the footer, which contains a bunch of
li elements that outline the currently saved keyboard bindings. Or maybe the page’s
<body> tag gets a giant
But WordPress gives us an elegant solution that doesn’t involve manipulating the page’s markup or document-object model (DOM). Here it is:
The Smart Way:
To understand how
wp_localize_script() works, let’s look at a highly simplified version of the “Keyboard Shortcuts” plugin’s code:
Passing the Data from PHP
Here’s a simplified version of the PHP we’re using to do two related things:
Our actual use of the data would be too complicated to simplify, so here we’ll just create a very simple use case: we’re going to create a browser alert with the first saved binding.
/* Environment: We're in wpshout_demo-update-shortcut.js */ // Access 'keys' element of passedData object var shortcutKeys = passedData.keys; // Create a browser alert with the first element of passedData alert( shortcutKeys );
Again, these code snippets are both somewhat simplified. With these examples under your belt, I invite you to browse the plugin code to learn how we’re actually creating browser shortcuts in the post editor.
You’re hopefully thinking, “
wp_localize_script() is incredibly cool.” A few notes to keep in mind:
- You need to register and enqueue your script before passing data to it. In our case, we’re doing both things in one function—which is probably not the best for code readability.
- You can pass lots of stuff all at once. We’ve only got a set of
'keys'to pass, but if you needed more data you could really load up the
$dataToPassassociative array with lots of kinds of data.
- Wondering about the name? Why
wp_localize_script()started out as an i18n thing, and turned out to be massively useful for a lot of other uses.
Now You Understand
If you’re writing code that spans the back and front end, I know you’ll love
wp_localize_script(). It’ll let you stop creating invisible
Thanks for reading!
Image credit: Nelson L.