Building a Gutenberg Sidebar

Previous Lesson
Next Lesson

Gutenberg Sidebar – Enqueueing JavaScript for the Block Editor

Building a Gutenberg Sidebar Gutenberg Sidebar – Enqueueing JavaScript for the Block Editor
Gutenberg Sidebar - Enqueueing JavaScript for the Block Editor

Now that we have our class structure, let’s begin by enqueueing our JavaScript file for use in the Block Editor.

As a reminder, here is our current folder structure and the files/folders we’ll be concentrating on.

.
└── landing-page-gutenberg-template/
    ├── .babelrc
    ├── autoloader.php
    ├── landing-page-gutenberg-template.php
    ├── package.json
    ├── webpack.config.js
    ├── dist/
    │   ├── sidebar.js (compiled JS)
    │   └── style.css (compiled SCSS)
    ├── includes (Include files go here)
    ├── languages (.mo, .po, .json files go here)
    └── src/
        ├── js/
        │   └── index.js
        └── scss/
            ├── style.scss
            └── common.scss

Code language: AsciiDoc (asciidoc)

Creating the Enqueue Class

Let’s begin by creating a file class-enqueue.php in the includes folder.

.
└── landing-page-gutenberg-template/
    ├── includes/
    │   └── class-enqueue.php
    └── src/
        └── js/
            └── sidebar.js

Code language: AsciiDoc (asciidoc)

The enqueue class will be fairly simple. Here’s the entire code for the enqueue class.

<?php
/**
 * Enqueue assets.
 *
 * @package wpajax-landing
 */

namespace WPAndAjax\Includes;

/**
 * Enqueue class.
 */
class Enqueue {

	/**
	 * Class runner.
	 *
	 * @since 1.0.0
	 */
	public function run() {
		add_action( 'enqueue_block_editor_assets', array( $this, 'editor_enqueue_assets' ) );
	}

	/**
	 * Enqueue block assets.
	 *
	 * @since 1.0.0
	 */
	public function editor_enqueue_assets() {
		// Register the block script.
		wp_enqueue_script(
			'wpajax-gutenberg-sidebar',
			WPAJAX_LANDING_URL . 'dist/sidebar.js',
			array( 'wp-blocks', 'wp-i18n', 'wp-element', 'wp-editor', 'wp-plugins', 'wp-edit-post', 'wp-data' ),
			WPAJAX_LANDING_VERSION,
			true
		);

		wp_set_script_translations( 'wpajax-gutenberg-sidebar', 'landing-page-gutenberg-template', WPAJAX_LANDING_DIR . 'languages/' );
	}
}

Code language: PHP (php)

Dissecting the Enqueue Class

Let’s dissect several portions of the enqueue class so we know exactly what’s going on. Let’s start with the namespace.

The Namespace

namespace WPAndAjax\Includes;
Code language: PHP (php)

If you remember way back when we declared a namespace variable and set up our autoloader, we used the base namespace of WPAndAjax.

Since our autoloader expects the namespaces to reflect folder structure, we declare the folder name as part of the namespace. Since class-enqueue.php is in the includes folder, the namespace reflects this.

The Class Runner

For the majority of this series, we’ll skip the constructor and create a run method that can be invoked, which will start the process of initializing the hooks needed for the class.

/**
 * Class runner.
 *
 * @since 1.0.0
 */
public function run() {
	add_action( 'enqueue_block_editor_assets', array( $this, 'editor_enqueue_assets' ) );
}

Code language: PHP (php)

Within the run method is our attempt to hook into an action called enqueue_block_editor_assets.

/**
 * Class runner.
 *
 * @since 1.0.0
 */
public function run() {
	add_action( 'enqueue_block_editor_assets', array( $this, 'editor_enqueue_assets' ) );
}

Code language: PHP (php)

According to the hook documentation for enqueue_block_editor_assets, the action is invoked after the scripts have been loaded for the Block Editor and before the action admin_enqueue_scripts. The hook/action admin_enqueue_scripts is generally used to load scripts for the various admin screens inside the WordPress dashboard.

Our callback method is named editor_enqueue_assets. Let’s dive into that.

Enqueueing Scripts

/**
 * Enqueue block assets.
 *
 * @since 1.0.0
 */
public function editor_enqueue_assets() {
	// Register the block script.
	wp_enqueue_script(
		'wpajax-gutenberg-sidebar',
		WPAJAX_LANDING_URL . 'dist/sidebar.js',
		array(
			'wp-blocks',
			'wp-i18n',
			'wp-element',
			'wp-editor',
			'wp-plugins',
			'wp-edit-post',
			'wp-data',
		),
		WPAJAX_LANDING_VERSION,
		true
	);

	wp_set_script_translations(
		'wpajax-gutenberg-sidebar',
		'landing-page-gutenberg-template',
		WPAJAX_LANDING_DIR . 'languages/'
	);
}
Code language: PHP (php)

Within the callback method, we just straight-up enqueue the script with several dependencies. For more about wp_enqueue_script, please check out my article about enqueueing assets. Missing in this method is any kind of page detection.

Since we want our sidebar on every editor that supports the Block Editor, we essentially enqueue the script globally every time the Block Editor is present.

Dependencies

For our sidebar, we need several dependencies. We can adjust these later for script dependencies we may not need.

wp_enqueue_script(
	'wpajax-gutenberg-sidebar',
	WPAJAX_LANDING_URL . 'dist/sidebar.js',
	array(
		'wp-blocks',
		'wp-i18n',
		'wp-element',
		'wp-editor',
		'wp-plugins',
		'wp-edit-post',
		'wp-data',
	),
	WPAJAX_LANDING_VERSION,
	true
);

Code language: PHP (php)

Finally, we pass a version constant (we defined this in the base plugin file) and pass true to the last argument, which tells us to load our script in the footer instead of in the header. It’s generally a best practice to load scripts in the footer for performance reasons.

Translating JavaScript Files

Of note is our script handle, which is wpajax-gutenberg-sidebar. The script handle is a nice addition in case other plugins need to dequeue it (de-register) and is also useful for script translations.

For our script translations, we use the WordPress core function wp_set_script_translations.

wp_set_script_translations(
	'wpajax-gutenberg-sidebar',
	'landing-page-gutenberg-template',
	WPAJAX_LANDING_DIR . 'languages/'
);
Code language: PHP (php)

The first argument is the script handle, which in our case is wpajax-gutenberg-sidebar.

wp_set_script_translations(
	'wpajax-gutenberg-sidebar',
	'landing-page-gutenberg-template',
	WPAJAX_LANDING_DIR . 'languages/'
);

Code language: PHP (php)

The second argument is our plugin’s text domain.

wp_set_script_translations(
	'wpajax-gutenberg-sidebar',
	'landing-page-gutenberg-template',
	WPAJAX_LANDING_DIR . 'languages/'
);

Code language: PHP (php)

The third argument is optional, and if you’re hosting on the WordPress Plugin Directory, you can typically ignore this argument. However, if you do not plan to host on .org and want to explicitly tell WordPress where your translation files are located, you can set this argument. It requires the absolute path to the languages folder in your plugin.

wp_set_script_translations(
	'wpajax-gutenberg-sidebar',
	'landing-page-gutenberg-template',
	WPAJAX_LANDING_DIR . 'languages/'
);

Code language: PHP (php)

I’ll cover how to handle translations inside WordPress in a separate series. For now, let’s just assume it works.

And that’s it for our enqueue class. Now let’s wire up the JavaScript file so we know it actually loaded inside the Block Editor.

Our JavaScript File

We’ll be editing our main JavaScript file index.js in the src folder.

.
└── landing-page-gutenberg-template/
    ├── dist/
    │   └── sidebar.js (compiled)
    └── src/
        └── js/
            └── index.js

Code language: AsciiDoc (asciidoc)

Within index.js, we just include a simple alert so we can tell if our script is indeed running inside the Block Editor.

alert("Hi there");
Code language: JavaScript (javascript)

To create sidebar.js in our dist folder (think back to the post on Webpack), we’ll run npm run build inside our main folder via the command line.

npm run build
Code language: Bash (bash)

As a reminder, here’s what’s currently in sidebar.js in the dist folder.

(()=>{alert("Hi there")})();
Code language: JavaScript (javascript)

We’re set for now with the JavaScript file. Now let’s wire up our base class to reference our class-enqueue.php file.

Wiring Up the Enqueue Class

In our main class, you may remember we had a blank plugins_loaded method.

/**
 * Fired when the plugins for WordPress have finished loading.
 */
public function plugins_loaded() {

}
Code language: PHP (php)

This method is called via the plugins_loaded WordPress action.

Let’s set it up to run our enqueue class.

/**
 * Fired when the plugins for WordPress have finished loading.
 */
public function plugins_loaded() {

	// Admin enqueue actions.
	$this->admin_enqueue = new \WPAndAjax\Includes\Enqueue();
	$this->admin_enqueue->run();
}

Code language: PHP (php)

We first instantiate the Enqueue class and call a public method called run, which will initialize our hooks.

Testing Our Script

With everything wired up, our JavaScript file is ready for testing. Assume you are using the Block Editor, edit or add a post in the admin.

Block Editor Alert Prompt
Block Editor Alert Prompt

Conclusion

We now have some JavaScript outputting in our Block Editor.

Custom Gutenberg sidebars typically rely on post meta to store its data. Let’s cover how to initialize some meta boxes for use in the Block Editor. We’ll be taking a small break from JavaScript for now.

Previous Lesson
Back to Series
Next Lesson