JavaScript Modules In WordPress

By: Ryan Kienstra on: January 25, 2015  in: JavaScript

JavaScript modulesMost JavaScript files in WordPress are actually modules.

This makes all of the variables and functions private.

And lets you control what should be public.

JavaScript modules are:

  • More secure
  • Easier to change

Creating A Module

Wrap the entire file in a function.

( function( $ ) {
        // file contents

} )( jQuery );

This protects the file from the global namespace.

Variables declared in the file will be private.

How It Works

It’s a self-executing, anonymous function.

The function is:

function( $ ) {
        // file contents

You execute it by:

  • Putting ( ) after it
  • Optionally passing arguments: ( jQuery )
( function( $ ) {
        // file contents

} )( jQuery );

This passes jQuery as an argument for the parameter $.

So when you use $ in the file, it will be jQuery.

Example JavaScript Modules

Here’s the core WordPress file customize-controls.js:

(function( exports, $ ){
        // code omitted

        // end of file
})( wp, jQuery );

It passes two variables to the module:

  • exports is wp
  • $ is jQuery

WP core files with JavaScript modules include:

Private Variables

Variables declared in the JavaScript module will be private.

Begin the function body with var, followed by the private variables.

You might read my guide to JavaScript variable declaration.

( function( $ ) {
        var foo , bar; // private variable declarations 
        foo = 'example string';

} )( jQuery );

Exposing Variables

To make variables accessible outside of the file, there are 2 options.

Option 1: Return them in an object.

var exampleModule = 
( function( $ ) {
        var foo , bar;
        foo = 'example string';
        return { foo : foo };

} )( jQuery );

Give the entire file (function) a name: exampleModule.

Return whatever you want to be public: return { foo : foo };

To access foo outside of this file, use

For example, I wrote a file of utility functions in my plugin Adapter Widget Rows.

But I only wanted one function to be public.

So I only returned that.

return { manageAmountsOfWidgetsAndRows : manageAmountsOfWidgetsAndRows };

Here is the file:

var awrUtility =
( function( $ ) {
	var manageAmountsOfWidgetsAndRows , manageSidebar , hideOrShowButtonToDeleteSidebar ,
        // variables and functions omitted
        return { manageAmountsOfWidgetsAndRows : manageAmountsOfWidgetsAndRows };

} )( jQuery );

Another JS file can call this function with awrUtility.manageAmountsOfWidgetsAndRows().

The other functions and variables in awrUtility remain private.

Option 2: Global Variables

This is another common way to expose variables in JavaScript modules.

You can attach variables to a global variable.

Any variable is global if it’s not declared in a function.

awrUtility (above) is global because it’s declared before the function.

For example, Weston Ruter suggested that private functions in a core WordPress file be exposed for unit testing.

The global variable wp.customize is available inside the file.

In the file, api = wp.customize

So I created the new variable api.utils.

 api.utils = {};

And attached the functions to that.

api.utils.bubbleChildValueChanges = function ( instance, properties ) { 

(See it in the full file)

Why Use JavaScript Modules?

Your files will be easier to change.

By making functions private, there will be fewer function calls between modules.

And they’ll be more secure because nothing else can change the private variables.

What setup do you use for your JavaScript files?

Do you have any questions about JavaScript modules?

Leave a comment