Tutorials Archives

Jan 05 2019

Custom Rewrite Rules for Custom Post Types and Taxonomies

Getting custom URL structures that differ from standard WordPress convention can be tough, even confusing.

When you register a custom post type, you get these URLs:

Singular Page: https://domain.com/cpt-slug/post-name-slug/
Paginated Singular Pages: https://domain.com/cpt-slug/post-name-slug/2/
Archive Page: https://domain.com/cpt-archive-slug/
Paginated Archive Pages: https://domain.com/cpt-slug/post-name-slug/page/2/
Trackback Page: https://domain.com/cpt-slug/post-name-slug/trackback/
Feed Pages: https://domain.com/cpt-slug/post-name-slug/feed/rss/, https://domain.com/cpt-slug/post-name-slug/rss/
Comment Page: https://domain.com/cpt-slug/post-name-slug/comment-page/
Embed Page: https://domain.com/cpt-slug/post-name-slug/embed/
Attachment:
- Attachment Page: https://domain.com/cpt-slug/post-name-slug/attachment/my-attachment-slug/
- Attachment Trackback Page: https://domain.com/cpt-slug/post-name-slug/attachment/my-attachment-slug/trackback/
- Attachment Feed Pages: https://domain.com/cpt-slug/post-name-slug/attachment/my-attachment-slug/feed/rss/ , https://domain.com/cpt-slug/post-name-slug/attachment/my-attachment-slug/rss/
- Attachment Comment Page: https://domain.com/cpt-slug/post-name-slug/attachment/my-attachment-slug/comment-page/
- Attachment Embed Page: https://domain.com/cpt-slug/post-name-slug/attachment/my-attachment-slug/embed/

When you register a custom taxonomy, you get these URLs:

Term Archive Page: https://domain.com/custom-taxonomy-slug/term-slug/
Paginated Archive Pages: https://domain.com/custom-taxonomy-slug/term-slug/page/2/
Embed Page: https://domain.com/custom-taxonomy-slug/term-name-slug/embed/
Feed Pages: https://domain.com/custom-taxonomy-slug/term-name-slug/feed/rss/, https://domain.com/tax-slug/term-name-slug/rss/

So, if you want anything else, you need to do something custom. For example, if you want date archive pages with your custom post type or if you want to introduce a taxonomy term in the URL, you must add some custom code.

Setup

So let's setup a plugin main file. First create a folder called post-type-taxonomy-rewrite.

	<?php
	/**
	* Plugin Name: WPS Post Type Taxonomy Rewrite
	* Plugin URI: https://wpsmith.net
	* Description: Rewrite for {taxonomy}/{postname} rewrites.
	* Author: Travis Smith <[email protected]>
	* Author URI: https://wpsmith.net
	* Text Domain: wps-rewrite
	* Domain Path: /languages
	* Version: 0.1.0
	*/

	/**
	* Plugin main file.
	*
	* @package WPS\Plugins\Rewrite
	* @author Travis Smith <[email protected]>
	* @license GPL-2.0+
	* @link https://wpsmith.net/
	*/

	namespace WPS\Plugins\Rewrite\PostTypeTaxonomy;

view raw post-type-taxonomy-rewrite-resources.php hosted with ❤ by GitHub

Create a composer.json file where we can require my rewrite package (wpsmith/rewrite) via composer.

	{
	"name": "wpsmith/post-type-taxonomy-rewrite",
	"description": "Rewrite for {taxonomy}/{postname} rewrites.",
	"type": "project",
	"license": "GPLv2+",
	"authors": [
	{
	"name": "Travis Smith",
	"email": "[email protected]"
	}
	],
	"minimum-stability": "dev",
	"require": {
	"wpsmith/rewrite": "dev-master"
	}
	}

view raw composer.json hosted with ❤ by GitHub

Once we have this file, we can do a composer install which will install our packages into a folder called vendor.

Now in the plugin file (post-type-taxonomy-rewrite.php), we need to require the composer autoloader.

	// Add autoloader.
	require 'vendor/autoload.php';

view raw post-type-taxonomy-rewrite-videos.php hosted with ❤ by GitHub

So now we should have this:

post-type-taxonomy-rewrite/
|- composer.json
|- post-type-taxonomy-rewrite.php
|- vendor/

Custom Post Type / Taxonomy Example

For example, let's say we want this pattern(domain.com/{post-type-slug}/{term}/{postname}):

Single Custom Post Type Post: https://domain.com/resource/tutorials/setting-up-something
Custom Taxonomy Archive: https://domain.com/resource/tutorials/
Custom Post Type Archive: https://domain.com/resource/

Now, I have written a class that you can use to make this extremely easy!

Setup

Now, create a resources.php file to contain our post type and taxonomy registration code for resource and resource-type.

	<?php
	/**
	* Post Type and Taxonomy Registration.
	*
	* Resource Post Type & Resource Type Taxonomy.
	*
	* @package WPS\Plugins\Rewrite
	* @author Travis Smith <[email protected]>
	* @license GPL-2.0+
	* @link https://wpsmith.net/
	*/

	namespace WPS\Plugins\Rewrite\PostTypeTaxonomy;

	add_action( 'init', '\WPS\Plugins\Rewrite\PostTypeTaxonomy\register_tax_resource_type' );
	/**
	* Register the Resource Type taxonomy
	*
	*/
	function register_tax_resource_type() {
	$labels = array(
	'name' => __( 'Resource Types', 'wps' ),
	'singular_name' => __( 'Type', 'wps' ),
	'search_items' => __( 'Search Types', 'wps' ),
	'popular_items' => __( 'Popular Types', 'wps' ),
	'all_items' => __( 'All Types', 'wps' ),
	'parent_item' => __( 'Parent Type', 'wps' ),
	'parent_item_colon' => __( 'Parent Type:', 'wps' ),
	'edit_item' => __( 'Edit Type', 'wps' ),
	'update_item' => __( 'Update Type', 'wps' ),
	'add_new_item' => __( 'Add New Type', 'wps' ),
	'new_item_name' => __( 'New Type', 'wps' ),
	'separate_items_with_commas' => __( 'Separate Types with commas', 'wps' ),
	'add_or_remove_items' => __( 'Add or remove Types', 'wps' ),
	'choose_from_most_used' => __( 'Choose from most used Types', 'wps' ),
	'menu_name' => __( 'Types', 'wps' ),
	);
	$args = array(
	'labels' => $labels,
	'public' => true,
	'show_in_nav_menus' => true,
	'show_ui' => true,
	'show_tagcloud' => false,
	'hierarchical' => true,
	'rewrite' => array( 'slug' => 'resource-type', 'with_front' => false ),
	'query_var' => true,
	'show_admin_column' => true,
	);
	register_taxonomy( 'resource_type', array( 'resource' ), $args );
	}

	add_action( 'init', '\WPS\Plugins\Rewrite\PostTypeTaxonomy\register_cpt_resource' );
	/**
	* Register the custom post type
	*
	* @since 1.2.0
	*/
	function register_cpt_resource() {

	$labels = array(
	'name' => __( 'Resources', 'wps' ),
	'singular_name' => __( 'Resource', 'wps' ),
	'add_new' => __( 'Add New', 'wps' ),
	'add_new_item' => __( 'Add New Resource', 'wps' ),
	'edit_item' => __( 'Edit Resource', 'wps' ),
	'new_item' => __( 'New Resource', 'wps' ),
	'view_item' => __( 'View Resource', 'wps' ),
	'search_items' => __( 'Search Resources', 'wps' ),
	'not_found' => __( 'No Resources found', 'wps' ),
	'not_found_in_trash' => __( 'No Resources found in Trash', 'wps' ),
	'parent_item_colon' => __( 'Parent Resource:', 'wps' ),
	'menu_name' => __( 'Resources', 'wps' ),
	);

	$args = array(
	'labels' => $labels,
	'hierarchical' => true,
	'supports' => array( 'title', 'editor', 'thumbnail', 'revisions', 'author', 'comments', 'discussion', 'page-attributes' ),
	'public' => true,
	'show_ui' => true,
	'show_in_menu' => true,
	'show_in_nav_menus' => true,
	'publicly_queryable' => true,
	'exclude_from_search' => false,
	'has_archive' => true,
	'query_var' => true,
	'can_export' => true,
	'rewrite' => array( 'slug' => 'resource', 'with_front' => false ),
	'menu_icon' => 'dashicons-format-aside',
	);

	register_post_type( 'resource', $args );

	}

view raw resources.php hosted with ❤ by GitHub

So now we should have this:

post-type-taxonomy-rewrite/
|- composer.json
|- post-type-taxonomy-rewrite.php
|- resources.php
|- vendor/

Doing the Rewrites

Then let's create a function:

	/**
	* Does the resources rewrites.
	*/
	function do_resources() {
	// Require post types file.
	require_once 'resources.php';

	// Do the rewrite for resources.
	try {

	// Create the rewrite object connecting the post type and taxonomy.
	$resource_resource_type = new \WPS\Rewrite\PostTypeByTaxonomy( array(
	'post_type' => 'resource',
	'taxonomy' => 'resource_type',
	) );

	// Set the order of the rewrite to `%post_type%/%term%`. Defaults to `%term%/%post_type%`.
	$resource_resource_type->set_order( [
	'%post_type%',
	'%term%',
	] );

	// Add all the rewrites. This includes the main, embed, feed, pagination, and date URLs.
	$resource_resource_type->add_all_rewrites();

	} catch ( \Exception $e ) {
	// do nothing right now.
	// @todo Maybe do something.
	}
	}

	// Do it!
	do_resources();

view raw post-type-taxonomy-rewrite-resources.php hosted with ❤ by GitHub

That's it!

On Activation

Because this is a plugin, we need to flush the rewrite rules when the plugin is activated. So in the plugin file (post-type-taxonomy-rewrite.php), let's flush the rules.

	register_activation_hook( __FILE__, '\WPS\Plugins\Rewrite\PostTypeTaxonomy\on_activation' );
	/**
	* Flush rules on activation.
	*/
	function on_activation() {

	// Registering Resources.
	register_tax_resource_type();
	register_cpt_resource();

	// Flush the rules.
	flush_rewrite_rules();

	}

view raw post-type-taxonomy-rewrite-resources.php hosted with ❤ by GitHub

Taxonomy / Custom Post Type Example

What if you have a hierarchical post type that you wanted to use with this pattern (domain.com/{term}/{post-type-slug}/{postname}):

Single Parent Custom Post Type Post: https://domain.com/email/landing-page/selling-something
Single Child Custom Post Type Post: https://domain.com/email/landing-page/selling-parent/selling-something
Custom Taxonomy Archive: https://domain.com/email/

Setup

Now, create a landing-pages.php file to contain our post type and taxonomy registration code for landing_page and campaign_type (this replaces resources.php).

	<?php
	/**
	* Post Type and Taxonomy Registration.
	*
	* Landing Page Post Type & Campaign Type Taxonomy.
	*
	* @package WPS\Plugins\Rewrite
	* @author Travis Smith <[email protected]>
	* @license GPL-2.0+
	* @link https://wpsmith.net/
	*/

	namespace WPS\Plugins\Rewrite\PostTypeTaxonomy;

	add_action( 'init', '\WPS\Plugins\Rewrite\PostTypeTaxonomy\register_cpt_landing_pages' );
	/**
	* Register the Landing Pages Post Type.
	*/
	function register_cpt_landing_pages() {

	$labels = array(
	'name' => __( 'Landing Pages', 'wps' ),
	'singular_name' => __( 'Landing Page', 'wps' ),
	);

	$args = array(
	'label' => __( 'Landing Pages', 'wps' ),
	'labels' => $labels,
	'description' => '',
	'public' => true,
	'publicly_queryable' => true,
	'show_ui' => true,
	'delete_with_user' => false,
	'show_in_rest' => true,
	'rest_base' => '',
	'rest_controller_class' => 'WP_REST_Posts_Controller',
	'has_archive' => false,
	'show_in_menu' => true,
	'show_in_nav_menus' => true,
	'exclude_from_search' => true,
	'capability_type' => 'post',
	'map_meta_cap' => true,
	'hierarchical' => false,
	'rewrite' => array( 'slug' => 'landing-page', 'with_front' => true ),
	'query_var' => true,
	'menu_position' => 5,
	'supports' => array( 'title', 'editor', 'thumbnail' ),
	'taxonomies' => array( 'campaign_type' ),
	'menu_icon' => 'dashicons-analytics',
	);

	register_post_type( 'landing_page', $args );
	}

	add_action( 'init', '\WPS\Plugins\Rewrite\PostTypeTaxonomy\register_tax_campaign_type' );
	/**
	* Register the Campaign Type Custom Taxonomy.
	*/
	function register_tax_campaign_type() {

	$labels = array(
	'name' => __( 'Campaign Types', 'wps' ),
	'singular_name' => __( 'Campaign Type', 'wps' ),
	);

	$args = array(
	'label' => __( 'Campaign Types', 'wps' ),
	'labels' => $labels,
	'public' => true,
	'publicly_queryable' => true,
	'hierarchical' => true,
	'show_ui' => true,
	'show_in_menu' => true,
	'show_in_nav_menus' => true,
	'query_var' => true,
	'rewrite' => array( 'slug' => 'campaign_type', 'with_front' => true, ),
	'show_admin_column' => false,
	'show_in_rest' => true,
	'rest_base' => 'campaign_type',
	'rest_controller_class' => 'WP_REST_Terms_Controller',
	'show_in_quick_edit' => false,
	);

	register_taxonomy( 'campaign_type', array( 'landing_page' ), $args );

	// Make taxonomy single term only.
	// 'type' can be 'radio' or 'select' (default: radio)
	new \WPS\Taxonomies\SingleTermTaxonomy( 'campaign_type', array( 'landing_page' ), 'radio' );
	}

view raw landing-pages.php hosted with ❤ by GitHub

So now we should have this:

post-type-taxonomy-rewrite/
|- composer.json
|- post-type-taxonomy-rewrite.php
|- landing-pages.php
|- vendor/

With Landing Pages, I added an additional class SingleTermTaxonomy to ensure that the taxonomy, campaign_type would always have only one term selected. In order to use this additional class, composer.json needs to be updated.

	{
	"name": "wpsmith/post-type-taxonomy-rewrite",
	"description": "Rewrite for {taxonomy}/{postname} rewrites.",
	"type": "project",
	"license": "GPLv2+",
	"authors": [
	{
	"name": "Travis Smith",
	"email": "[email protected]"
	}
	],
	"minimum-stability": "dev",
	"require": {
	"wpsmith/single-term-taxonomy": "dev-master",
	"wpsmith/rewrite": "dev-master"
	}
	}

view raw composer-landing-pages.json hosted with ❤ by GitHub

SingleTermTaxonomy is not required, and if you do not wish to use this class, then simply delete lines 88-89.

	new \WPS\Taxonomies\SingleTermTaxonomy( 'campaign_type', array( 'landing_page' ), 'radio' );
	}

view raw landing-pages.php hosted with ❤ by GitHub

Doing the Rewrites

Then let's create a function:

	/**
	* Does the landing-pages rewrites.
	*/
	function do_landing_pages() {
	// Require post types file.
	require_once 'landing-pages.php';

	// Do the rewrite for landing pages.
	try {

	// Create the rewrite object connecting the post type and taxonomy.
	$landing_page_campaign_type = new \WPS\Rewrite\PostTypeByTaxonomy( array(
	'post_type' => 'landing_page',
	'taxonomy' => 'campaign_type',
	) );

	// Set the order of the rewrite to `%post_type%/%term%`. Defaults to `%term%/%post_type%`.
	$landing_page_campaign_type->set_order( [
	'%term%',
	] );

	// Add the feed/embed rewrite URLs.
	$landing_page_campaign_type->add_embed_rewrites();
	$landing_page_campaign_type->add_feed_rewrites();

	} catch ( \Exception $e ) {
	// do nothing right now.
	// @todo Maybe do something.
	}
	}

	// Do it!
	do_landing_pages();

view raw post-type-taxonomy-rewrite-landing-pages.php hosted with ❤ by GitHub

That's it!

On Activation

Because this is a plugin, we need to flush the rewrite rules when the plugin is activated. So in the plugin file (post-type-taxonomy-rewrite.php), let's flush the rules.

	register_activation_hook( __FILE__, '\WPS\Plugins\Rewrite\PostTypeTaxonomy\on_activation' );
	/**
	* Flush rules on activation.
	*/
	function on_activation() {

	// Register Landing Pages.
	register_cpt_landing_pages();
	register_tax_campaign_type();


	// Flush the rules.
	flush_rewrite_rules();

	}

view raw post-type-taxonomy-rewrite-landing-pages.php hosted with ❤ by GitHub

Prefix / Custom Post Type Example

What if you have a post type that you wanted to add a prefix slug, the date archives, and so use with this pattern (domain.com/{prefix}/{post-type-slug}/{postname}):

Single Custom Post Type Post: https://domain.com/video/some-music-video
Date Archives: https://domain.com/video/2019, https://domain.com/video/2019/01, and https://domain.com/video/2019/01/05
Custom Post Type Archive: https://domain.com/videos/

Setup

Now, create a videos.php file to contain our post type and taxonomy registration code for video (this replaces resources.php or landing-pages.php).

	<?php
	/**
	* Post Type and Taxonomy Registration.
	*
	* Video Post Type.
	*
	* @package WPS\Plugins\Rewrite
	* @author Travis Smith <[email protected]>
	* @license GPL-2.0+
	* @link https://wpsmith.net/
	*/

	namespace WPS\Plugins\Rewrite\PostTypeTaxonomy;

	add_action( 'init', '\WPS\Plugins\Rewrite\PostTypeTaxonomy\register_cpt_videos' );
	/**
	* Register the Video Post Type.
	*/
	function register_cpt_videos() {

	$labels = array(
	'name' => __( 'Videos', 'wps' ),
	'singular_name' => __( 'Video', 'wps' ),
	);

	$args = array(
	'label' => __( 'Videos', 'wps' ),
	'labels' => $labels,
	'description' => '',
	'public' => true,
	'publicly_queryable' => true,
	'show_ui' => true,
	'delete_with_user' => false,
	'show_in_rest' => true,
	'rest_base' => '',
	'rest_controller_class' => 'WP_REST_Posts_Controller',
	'has_archive' => 'videos',
	'show_in_menu' => true,
	'show_in_nav_menus' => true,
	'exclude_from_search' => true,
	'capability_type' => 'post',
	'map_meta_cap' => true,
	'hierarchical' => false,
	'rewrite' => array( 'slug' => 'video', 'with_front' => true ),
	'query_var' => true,
	'menu_position' => 5,
	'supports' => array( 'title', 'editor', 'thumbnail' ),
	'menu_icon' => 'dashicons-video-alt3',
	);

	register_post_type( 'video', $args );

	}

view raw videos.php hosted with ❤ by GitHub

So now we should have this:

post-type-taxonomy-rewrite/
|- composer.json
|- post-type-taxonomy-rewrite.php
|- videos.php
|- vendor/

Doing the Rewrites

Then let's create a function:

	/**
	* Does the videos rewrites.
	*/
	function do_videos() {
	// Require post types file.
	require_once 'videos.php';

	// Do the rewrite for landing pages.
	try {

	// Create the rewrite object connecting the post type and taxonomy.
	$videos = new \WPS\Rewrite\PostTypeRewrite( array(
	'post_type' => 'video',
	) );

	// Add all the rewrites. This includes the main, embed, feed, pagination, and date URLs.
	$videos->add_all_rewrites();


	} catch ( \Exception $e ) {
	// do nothing right now.
	// @todo Maybe do something.
	}
	}

	// Do it!
	do_videos();

view raw post-type-taxonomy-rewrite-videos.php hosted with ❤ by GitHub

That's it!

On Activation

Because this is a plugin, we need to flush the rewrite rules when the plugin is activated. So in the plugin file (post-type-taxonomy-rewrite.php), let's flush the rules.

	register_activation_hook( __FILE__, '\WPS\Plugins\Rewrite\PostTypeTaxonomy\on_activation' );
	/**
	* Flush rules on activation.
	*/
	function on_activation() {

	// Register Videos.
	register_cpt_videos();


	// Flush the rules.
	flush_rewrite_rules();

	}

view raw post-type-taxonomy-rewrite-videos.php hosted with ❤ by GitHub

Wrap-Up

If this was helpful, you can find all the code either in the gist or the Github repo (https://github.com/wpsmith/post-type-taxonomy-rewrite). Please feel free to let me know if there is anything I missed!

Jun 21 2018

WordPress JavaScript Manager Native Functions

WordPress has native PHP JavaScript management functions. Using these functions are better than manually adding <script> tags in the <head> or footer of the page. In this article, we will discuss:

PHP Constants for Debugging JavaScript
Registering and Deregistering Scripts
Enqueueing and Dequeueing Scripts
Localizing Scripts
Initializing Scripts
Modifying Script Tags on Print

PHP Constants for Debugging JavaScript

Most WordPress developers are familiar with WP_DEBUG and know how to use that to debug WordPress. WP_DEBUG is designed as a global for turning debugging on and off, but WP_DEBUG has no affect on JavaScript files. Fewer developers know about SCRIPT_DEBUG. While WP_DEBUG helps debug the PHP code, SCRIPT_DEBUG helps with JavaScript. SCRIPT_DEBUG will output the normal, non-minified version of the JavaScript files. For example, with SCRIPT_DEBUG will output wp-embed.js while normally WordPress will output wp-embed.min.js. You can use this constant to output minified and non-minified your plugin/theme JavaScript files dynamically. For example:

	<?php

	namespace MyPrefix\MyPluginOrTheme;

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	// JavaScript File
	$filename = "myscript{$suffix}.js";

	// CSS File
	$filename = "myscript{$suffix}.css";

view raw wp-script-debug-js-css.php hosted with ❤ by GitHub

Alternatively, you could use a function that will do this for you:

	<?php

	namespace MyPrefix\MyPluginOrTheme;

	/**
	* Gets the proper JavaScript filename based on SCRIPT_DEBUG.
	*
	* @param string $filename Filename without the extension.
	*
	* @return string JavaScript filename.
	*/
	function get_js_filename( $filename ) {
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	return "{$filename}{$suffix}.js";
	}

	$filename = get_js_filename( 'myscript' );

view raw wp-script-debug-get_js_filename.php hosted with ❤ by GitHub

Or, you can use a constant or multiple constants:

	<?php

	namespace MyPrefix\MyPluginOrTheme;

	// Define MULTIPLE Suffixes
	define( 'JS_SUFFIX', ( ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '.js' : '.min.js' ) );
	define( 'CSS_SUFFIX', ( ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '.css' : '.min.css' ) );

	// JavaScript file
	$filename = 'myscript' . JS_SUFFIX;

	// CSS file
	$filename = 'mystyle' . CSS_SUFFIX;

	// Define a SINGLE Suffix
	define( 'SCRIPT_SUFFIX', ( ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min' ) );

	// JavaScript file
	$filename = 'myscript' . SCRIPT_SUFFIX . '.js';

	// CSS file
	$filename = 'mystyle' . SCRIPT_SUFFIX . '.css';

view raw wp-script-debug-constants.php hosted with ❤ by GitHub

]

Or (just for fun) create a function for the suffix only:

	<?php

	namespace MyPrefix\MyPluginOrTheme;

	/**
	* Gets the proper JavaScript filename based on SCRIPT_DEBUG.
	*
	* @param string $filename Filename without the extension.
	*
	* @return string JavaScript filename.
	*/
	function get_suffix( $filename ) {
	static $suffix;

	if ( null !== $suffix ) {
	return $suffix;
	}
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	return $suffix;
	}

	$filename = 'myscript' . get_suffix() . 'js';

view raw wp-script-debug-get_suffix.php hosted with ❤ by GitHub

If SCRIPT_DEBUG is on, the filename will be my-js-file.js while if SCRIPT_DEBUG is false, the filename will be my-js-file.min.js. So if you have a Gulp/Grunt script or a PHPStorm File Watcher auto-minifying your JavaScript, WordPress will properly output the correct JavaScript file.

Registering and Deregistering Scripts

Why register your scripts?

DRY: The script manager allows you to re-use and output the script in various places of your code.
Integrations: The script manager allows for anyone to integrate, optimize, and build upon your script.
Prevents Duplication: A script using the script manager will only be printed on the page once.
Client Focused & Client Friendly: It allows your customers/clients to remove the scripts easily.

DRY

The first reason (and one which I agree) is perfect for coders who subscribe to DRY (Don't Repeat Yourself) coding, which most of us prefer. It optimizes your code and makes your code clean and readable. WordPress Core registers a ton of JavaScript files. Most notable of these are:

jquery (core and other parts—jquery-ui, jquery-effects)
thickbox
underscrore
backbone
media-element

If you are using any of these, please use the WordPress core version. It ensures the best experience.

Client Focused & Client Friendly

Many developers do not like the second reason. They want to control every aspect of their code because they are afraid that their client/customer or another developer will break their plugin. However, to me, this is not a good reason. If a customer/client breaks the plugin/site because they chose to copy/paste code and place it in their functions.php site, it is their fault, and they can pay you to fix it. But by providing the client/customer code that is changeable, it makes you look like a better developer, and you will have return customers/clients because they can trust that you have their best interests in mind.

Integrations & Prevents Duplication

Plugins like WP Rocket and other optimization plugins can detect and handled registered scripts much easier than functions that echo script elements at random places throughout the document. WordPress filters, like script_loader_src and script_loader_tag, can be used to amend how one or more registered scripts are loaded in the DOM by amending the tag attributes (see below for the advanced examples), and finally other scripts can use those scripts as dependencies themselves.

By using a script manager, WordPress tries to prevent duplication of scripts. For example, if one plugin outputs underscore via a script tag and the other developer uses WordPress's version, then multiple underscore scripts will be printed on the page, which obviously will lead to problems.

The Code: Registering/Deregistering Scripts

There is a function for registering a JavaScript file (wp_register_script) and one for deregistering a JavaScript file (wp_deregister_script). Now, many developers, and even those on developers.wordpress.org, recommend that you register scripts within the wp_enqueue_scripts hook. However, it is my opinion that you should always register scripts on init (for frontend scripts wrapped with ! is_admin() conditional) and admin_init (for admin scripts) hooks. For the purposes of this article, we will be focusing all of the examples to frontend JavaScript, so we won't be using the admin_init hook. This allows your customers/clients to manipulate the scripts however they need, if they need.

Registering JavaScript Files

wp_register_script($handle, $src, $deps, $ver, $in_footer) takes a couple parameters which are obvious: $handle (slug) $src (the script URL), $in_footer (whether to output in the head or footer). It is always recommended that $in_footer be true unless (1) there is a very specific reason for the script to be in the head (other than "my code doesn't work in the footer") or (2) you use defer. Two really good examples are Google Analytics and New Relic—both require to be run in the head at the top. IMHO Google Analytics should have the async attribute added to it. The two remaining parameters—dependencies ($deps) and version ($ver) are more fascinating.

Script Version (`$ver`)

Most people use a simple version number to identify the version (e.g., 0.0.1 or 2.1). In fact, most developers are either ignorant or lazy and only use the version of the theme or plugin via a constant or something hardcoded that never seems to change. So if you are doing development with an aggressively caching browser it becomes problematic and frustrating to ensure that your changes are being reflected in the DOM, even with browsersync or gulp-livereload. However, the best option is to do both the version of the plugin and the file version. If you are like me, changing the version of the file every time in the JavaScript file and the correlating PHP file is such a hassle. Being a stickler on this yet also lazy about versioning myself, I need something simple that would be cacheable and yet also cache bust when needed (on update/change). My goal is to load the JavaScript file via WordPress and forget about that part and work on the JavaScript file only. So, I use filemtime for file versioning within my PHP and maintain semantic versioning within the JavaScript file properly. filemtime helps me accomplish this. It returns the epoch time (e.g., 1529330834) of when the file was written/changed. So as long as the file does not change or update, the file will be cached.

So here is how I do versioning for my scripts:

	<?php

	namespace MyPrefix\MyPluginOrTheme;

	define( 'PLUGIN_VERSION', '1.0.0' );

	// Parent Theme Version
	$ver = PLUGIN_VERSION . '-' . filemtime( get_template_directory() . "/myscript$suffix.js" );

	// Child Theme Version
	$ver = PLUGIN_VERSION . '-' . filemtime( get_stylesheet_directory() . "/myscript$suffix.js" );

	// Plugin Version, assumes this PHP file is in the root of the plugin folder (e.g., ./wp-content/plugins/myplugin/script-dependencies.php)
	$ver = PLUGIN_VERSION . '-' . filemtime( get_plugin_dir( __FILE__ ) . "/myscript$suffix.js" );

view raw wp-script-dependencies.php hosted with ❤ by GitHub

The resulting filename will be something like myscript.js?ver=1.0.0-1528229721. This will make it easy to identify the version of the plugin while also ensuring that the correct version of the script is on the frontend. Even WordPress.com does something similar outputting files with the version of the file and a date (e.g., https://s1.wp.com/wp-content/js/mustache.js?ver=6.1.1-201824).

Script Dependencies (`$deps`)

Finally, $deps are really cool because when I output the file, WordPress will also output all the dependencies without me having to do it...but more on that in the next section.

Registering Scripts in Themes

For themes, you register files like this (using the previous best practice with the dynamic suffix):

	<?php

	namespace MyPrefix\MyTheme;

	define( 'MY_THEME_VERSION', '1.0.0' );

	add_action( 'init', __NAMESPACE__ . '\register_scripts' );
	/**
	* Register my scripts.
	*/
	function register_scripts() {

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	// Assumes the JS file is located in the js folder within the theme folder.
	wp_register_script(
	'myscript', // file slug
	get_stylesheet_directory_uri() . "/js/myscript$suffix.js", // file URL
	array(), // dependencies
	MY_THEME_VERSION . '-' . filemtime( get_stylesheet_directory() . "/js/myscript$suffix.js" ), // version
	true // in footer or not
	);

	wp_register_script(
	'jquery-myscript', // file slug
	get_stylesheet_directory_uri() . "/js/jquery.myscript$suffix.js", // file URL
	array( 'jquery' ), // dependencies
	MY_THEME_VERSION . '-' . filemtime( get_stylesheet_directory() . "/js/jquery.myscript$suffix.js" ), // version
	true // in footer or not
	);

	}

view raw wp-register-theme-script.php hosted with ❤ by GitHub

Alternatively, you could use a theme script register helper:

	<?php

	namespace MyPrefix\MyTheme;

	define( 'MY_THEME_VERSION', '1.0.0' );

	/**
	* Register my scripts.
	*
	* @param string $filename Filename.
	* @param string $theme_relative_path Relative path to file within theme folder.
	*/
	function register_theme_script( $filename, $theme_relative_path = '/', $dependencies = array(), $footer = true ) {

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	wp_register_script(
	str_replace( '.', '-', $filename ), // file slug without js extension
	get_stylesheet_directory_uri() . "{$theme_relative_path}{$filename}{$suffix}.js", // file URL
	$dependencies, // dependencies
	MY_THEME_VERSION . '-' . filemtime( get_stylesheet_directory() . "{$theme_relative_path}{$filename}{$suffix}.js" ), // version
	$footer // in footer or not
	);

	}

view raw wp-register-theme-function.php hosted with ❤ by GitHub

Registering Scripts in Plugins

For plugins, you register files like this (using the previous best practice with the dynamic suffix):

	<?php

	namespace MyPrefix\MyPlugin;

	define( 'MY_PLUGIN_VERSION', '1.0.0' );

	add_action( 'init', __NAMESPACE__ . '\register_scripts' );
	/**
	* Register my scripts.
	*/
	function register_scripts() {

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	// Assumes the JS file is located in the js folder within the plugin folder.
	wp_register_script(
	'myscript',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/myscript{$suffix}.js", // file URL
	array(), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/myscript{$suffix}.js" ), // version
	true
	);

	wp_register_script(
	'jquery-myscript',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/jquery.myscript{$suffix}.js", // file URL
	array( 'jquery' ), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/jquery.myscript{$suffix}.js" ), // version
	true
	);

	}

view raw wp-register-plugin-script.php hosted with ❤ by GitHub

Alternatively, you could use a plugin script register helper:

	<?php

	namespace MyPrefix\MyPlugin;

	define( 'MY_PLUGIN_VERSION', '1.0.0' );

	// Should be placed at the root of the plugin folder
	define( 'MY_PLUGIN_FILE', __FILE__ );

	/**
	* Register my scripts.
	*
	* @param string $filename Filename.
	* @param string $theme_relative_path Relative path to file within theme folder.
	*/
	function register_plugin_script( $filename, $theme_relative_path = '/', $dependencies = array(), $footer = true ) {

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	wp_register_script(
	str_replace( '.', '-', $filename ), // file slug without js extension
	get_plugin_dir( MY_PLUGIN_FILE ) . "{$theme_relative_path}{$filename}{$suffix}.js", // file URL
	$dependencies, // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "{$theme_relative_path}{$filename}{$suffix}.js" ), // version
	$footer // in footer or not
	);

	}

view raw wp-register-plugin-function.php hosted with ❤ by GitHub

Deregistering JavaScript Files

Deregistering is extremely straight forward as you can see here:

	<?php

	namespace MyPrefix\MyPluginOrTheme;

	// Deregister script by handle
	wp_deregister_script( 'myscript' );

view raw wp-deregister-script.php hosted with ❤ by GitHub

However, actually deregistering a script can be quite tricky. The main problem with deregistering scripts is deregistering AFTER it has been registered. For plugins, this is why registering a script and enqueueing (or just enqueueing) a script in the same function (without a do_action between them) is an unfriendly and bad idea.

For example, here are three bad ways to do it:

	<?php

	namespace MyPrefix\MyPlugin;

	define( 'MY_PLUGIN_VERSION', '1.0.0' );

	add_action( 'wp_enqueue_scripts', __NAMESPACE__ . '\wp_enqueue_scripts' );
	/**
	* Register my scripts.
	*/
	function wp_enqueue_scripts() {

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	// Assumes the JS file is located in the js folder within the plugin folder.
	wp_enqueue_script(
	'plugin-script',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/plugin-script{$suffix}.js", // file URL
	array(), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/plugin-script{$suffix}.js" ), // version
	true
	);

	}

view raw wp-register-script-bad-0.php hosted with ❤ by GitHub

	<?php

	namespace MyPrefix\MyPlugin;

	define( 'MY_PLUGIN_VERSION', '1.0.0' );

	add_action( 'wp_enqueue_scripts', __NAMESPACE__ . '\wp_enqueue_scripts' );
	/**
	* Register my scripts.
	*/
	function wp_enqueue_scripts() {

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	// Assumes the JS file is located in the js folder within the plugin folder.
	wp_register_script(
	'plugin-script',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/plugin-script{$suffix}.js", // file URL
	array(), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/plugin-script{$suffix}.js" ), // version
	true
	);

	wp_enqueue_script( 'plugin-script' );

	}

view raw wp-register-script-bad-1.php hosted with ❤ by GitHub

https://gist.github.com/6e676ff6c5516427bb04aac361cacf00

This last one looks that most right but the problem is that they both are hooked at the same priority and there is no way to hook in between the functions to do anything.

Here is a better way:

	<?php

	namespace MyPrefix\MyPlugin;

	define( 'MY_PLUGIN_VERSION', '1.0.0' );

	add_action( 'wp_enqueue_scripts', __NAMESPACE__ . '\register_scripts' );
	/**
	* Register my scripts.
	*/
	function register_scripts() {

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	// Assumes the JS file is located in the js folder within the plugin folder.
	wp_register_script(
	'plugin-script',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/plugin-script{$suffix}.js", // file URL
	array(), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/plugin-script{$suffix}.js" ), // version
	true
	);

	}

	add_action( 'wp_enqueue_scripts', __NAMESPACE__ . '\wp_enqueue_scripts', 99 );
	/**
	* Register my scripts.
	*/
	function wp_enqueue_scripts() {

	wp_enqueue_script( 'plugin-script' );

	}

view raw wp-register-script-better.php hosted with ❤ by GitHub

This way, I can hook in between the functions within wp_enqueue_scripts hook to make any changes necessary.

Here is the best way (IMHO):

	<?php

	namespace MyPrefix\MyPlugin;

	define( 'MY_PLUGIN_VERSION', '1.0.0' );

	add_action( 'init', __NAMESPACE__ . '\register_scripts' );
	/**
	* Register my scripts.
	*/
	function register_scripts() {

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	// Assumes the JS file is located in the js folder within the plugin folder.
	wp_register_script(
	'plugin-script',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/plugin-script{$suffix}.js", // file URL
	array(), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/plugin-script{$suffix}.js" ), // version
	true
	);

	}

	add_action( 'wp_enqueue_scripts', __NAMESPACE__ . '\wp_enqueue_scripts' );
	/**
	* Register my scripts.
	*/
	function wp_enqueue_scripts() {

	wp_enqueue_script( 'plugin-script' );

	}

view raw wp-register-script-best.php hosted with ❤ by GitHub

So when do you deregister a script? You deregister a script for two primary reasons:

If you want to re-register the script with different arguments (primarily $src URL).
If you want to ensure the script never gets placed on the frontend period.

Warning: Whenever you deregister a script (e.g., myscript) without re-registering a new version of that script, any script dependent upon that script (e.g., myscript) will not output either.

So, consider this example. In wp-config.php, we have define( 'SCRIPT_DEBUG', true );. Now, let's say we have this in an active plugin:

	<?php

	namespace MyPrefix\MyPlugin;

	define( 'MY_PLUGIN_VERSION', '1.0.0' );

	add_action( 'init', __NAMESPACE__ . '\register_scripts' );
	/**
	* Register my scripts.
	*/
	function register_scripts() {

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	// Assumes the JS file is located in the js folder within the plugin folder.
	wp_register_script(
	'plugin-script-base',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/plugin-script-base{$suffix}.js", // file URL
	array( 'underscore' ), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/plugin-script-base{$suffix}.js" ), // version
	true
	);

	wp_register_script(
	'plugin-script',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/plugin-script{$suffix}.js", // file URL
	array( 'plugin-script-base' ), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/plugin-script{$suffix}.js" ), // version
	true
	);

	wp_register_script(
	'plugin-script-ext',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/plugin-script-ext{$suffix}.js", // file URL
	array( 'plugin-script' ), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/plugin-script-ext{$suffix}.js" ), // version
	true
	);

	}

	add_action( 'wp_enqueue_scripts', __NAMESPACE__ . '\wp_enqueue_scripts', 999 );
	/**
	* Outputs our plugin scripts
	*/
	function wp_enqueue_scripts() {

	wp_enqueue_script( 'plugin-script-ext' );

	}

view raw wp-plugin-scripts.php hosted with ❤ by GitHub

With a single statement, our use of the active plugin outputs three files on the frontend in this order:

js/plugin-script-base.js
js/plugin-script.js
js/plugin-script-ext.js

Now in our theme, say we have this in the functions.php file:

-<?php
-namespace MyPrefix\MyTheme;
-define( 'MY_THEME_VERSION', '1.0.0' );
-add_action( 'init', __NAMESPACE__ . '\deregister_scripts', 999 );
-/**
- * Register my scripts.
- */
-function deregister_scripts() {
-	// Assumes the JS file is located in the js folder within the plugin folder.
-	wp_deregister_script( 'plugin-script-base' );
-}

view raw wp-functions-theme-remove-scripts.php hosted with ❤ by GitHub

This function within functions.php will cause plugin-script and plugin-script-ext NOT to be placed on the frontend either because the WordPress script manager assumes that since plugin-script and plugin-script-ext are dependent upon plugin-script-base, they also won't work if plugin-script-base is missing. So WordPress will not output those files.

A Note

Many seasoned non-WordPress PHP developers will want to use their own version of jQuery. So they will deregister WordPress's jQuery and register their own. This may be a great idea for your own project ONLY that you will always control, but it is a terrible idea for any free/premium plugins and/or themes. Here's why:

Other themes/plugins depend on the same version of that script WordPress provides, so you may break the theme or plugins accidentally. So if you deregister it and register your own (even if the same version), when WordPress upgrades that script (i.e., jQuery), it could break everything. Alternatively, if you deregister jQuery (for example) and register another specific version (older or newer), then you may break current plugins.
WordPress may upgrade that script for security reasons and now you have opened a security hole. This will cause a massive amount of support requests if you sell a premium theme/plugin and cause harm to your brand/reputation. Or, you may not even be around to fix the problem for your client.

This is not client/customer friendly at all. As a developer, we need to get over our own opinions that using a CDN version or a specific version of a script is better and accept this part of WordPress and the WordPress ecosystem. Simply, play nice!

Enqueueing and Dequeueing Scripts

So far, we have only properly registered (or deregistered) the scripts within WordPress but that does not output the script tags on the frontend. To output the scripts on the frontend, you need to queue the script to be outputted by the WordPress script manager. To do this, you will need to use wp_enqueue_script.

wp_enqueue_script does two things:

Registers the script if it has not been registered already.
Outputs any files on the frontend during the wp_head hook via print_head_scripts (which calls wp_print_scripts hook) and wp_footer hook via _wp_footer_scripts which calls print_late_styles() and print_footer_scripts().

Sometimes, however, plugins and themes will just enqueue all their scripts even if the page doesn't use that particular script. They do this mostly because they provide their functionality through a shortcode and don't know how to properly test the page to determine whether that shortcode exists or not (blog post coming soon). In these cases, to increase the performance of your site, you may want to remove them. To do this, you will need to use wp_dequeue_script. Let's say that our script was "properly" registered on init and enqueued on wp_enqueue_scripts hooks. To dequeue the script, you just need to do this:

	<?php

	namespace MyPrefix\MyPlugin;

	define( 'MY_PLUGIN_VERSION', '1.0.0' );

	add_action( 'init', __NAMESPACE__ . '\remove_script' );
	/**
	* Register my scripts.
	*/
	function remove_script() {

	// Always dequeue the script
	wp_dequeue_script( 'plugin-script' );

	// Conditionally dequeue the script on archive pages
	if ( is_archive() ) {
	wp_dequeue_script( 'plugin-script' );
	}

	}

view raw wp-dequeue-script.php hosted with ❤ by GitHub

Localizing Scripts

Sometimes, our scripts need some additional information or configuration for whatever reason (localizing strings, configuring a JavaScript object, etc). This is done via wp_localize_script. wp_localize_script takes three parameters: $handle (string), $object_name (string), and $l10n (array).

When you localize your script, the object name (the second parameter) is the name of your JavaScript object, so best practice is that this parameter string would be camelCase. There are no checks within WordPress, so if you pass something like 'my-object', your JavaScript will fail.

Whatever PHP array is passed to wp_localize_script will be placed ahead of your external script tag. You can organize the $l10n array however you'd like, but over time, I have learned and now prefer to do something like this:

	$plugin_l10n = array(
	'strings' => array(
	'firstLabel' => __( 'Some string to translate', 'textdomain' ),
	'secondLabel' => __( 'Some string to translate', 'textdomain' ),
	),
	'config' => array(
	'something' => 'some-value',
	'somethingElse' => 3,
	),
	'debug' => ( ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) \|\| ( ! defined( 'SCRIPT_DEBUG' ) && defined( 'WP_DEBUG' ) && WP_DEBUG ) ),
	);

view raw wp-localize-plugin-script.php hosted with ❤ by GitHub

Again, please note that the string properties are camelCased.

Your JavaScript object will be placed in the Global Namespace. In our example, the JavaScript object is named pluginScriptExt. Therefore, our object is available globally via window.pluginScriptExt, so you must always prefix your objects unless you overwrite another object (if you need more information, see Mozilla's Global Object definition).

For example, if we take our script plugin-script-base from above, it is dependent on underscore. Underscore has a global JavaScript object named _. If we were to do this, we would render Underscore useless and _.each would not be available; instead _.strings would be.

	// Overwrites underscore
	wp_localize_script( 'plugin-script-ext', '_', $plugin_script_base_l10n );

view raw wp-localize-plugin-script-bad.php hosted with ❤ by GitHub

Alternatively, calling wp_localize_script twice on the same script with the same object name will overwrite the object, not extend the object. For example,

	// Create empty pluginScriptExt object -- won't work
	wp_localize_script( 'plugin-script-ext', 'pluginScriptExt', array() );

	// Add .config to pluginScriptExt object -- won't work
	wp_localize_script( 'plugin-script-ext', 'pluginScriptExt', array(
	'strings' => array(
	'firstLabel' => __( 'Some string to translate', 'textdomain' ),
	'secondLabel' => __( 'Some string to translate', 'textdomain' ),
	),
	) );

	// Add .strings to pluginScriptExt object -- won't work
	wp_localize_script( 'plugin-script-ext', 'pluginScriptExt', array(
	'config' => array(
	'something' => 'some-value',
	'somethingElse' => 3,
	),
	) );

view raw wp-localize-plugin-script-bad.php hosted with ❤ by GitHub

With this example, you will have:

	// Overwritten
	var pluginScriptExt = {
	config: {
	something: 'some-value',
	somethingElse: 3
	}
	};

view raw wpPluginScriptExt.js hosted with ❤ by GitHub

So, if you want to "expand" an object, it is better to create two objects (until WP_Scripts expands its capabilities).

	<?php

	namespace MyPrefix\MyPlugin;

	define( 'MY_PLUGIN_VERSION', '1.0.0' );

	add_action( 'init', __NAMESPACE__ . '\register_scripts' );
	/**
	* Register my scripts.
	*/
	function register_scripts() {

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	// Assumes the JS file is located in the js folder within the plugin folder.
	wp_register_script(
	'plugin-script-base',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/plugin-script-base{$suffix}.js", // file URL
	array( 'underscore' ), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/plugin-script-base{$suffix}.js" ), // version
	true
	);

	wp_register_script(
	'plugin-script',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/plugin-script{$suffix}.js", // file URL
	array( 'plugin-script-base' ), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/plugin-script{$suffix}.js" ), // version
	true
	);

	wp_register_script(
	'plugin-script-ext',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/plugin-script-ext{$suffix}.js", // file URL
	array( 'plugin-script' ), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/plugin-script-ext{$suffix}.js" ), // version
	true
	);

	// Create base object for pluginScriptExt object.
	wp_localize_script( 'plugin-script-ext', 'pluginScriptExtStrings', array(
	'firstLabel' => __( 'Some string to translate', 'textdomain' ),
	'secondLabel' => __( 'Some string to translate', 'textdomain' ),
	) );

	// Create base object for pluginScriptExt object.
	wp_localize_script( 'plugin-script-ext', 'pluginScriptExtConfig', array(
	'something' => 'some-value',
	'somethingElse' => 3,
	) );

	}

	add_action( 'wp_enqueue_scripts', __NAMESPACE__ . '\wp_enqueue_scripts', 999 );
	/**
	* Outputs our plugin scripts
	*/
	function wp_enqueue_scripts() {

	wp_enqueue_script( 'plugin-script-ext' );

	}

view raw wp-localize-plugin-script-2.php hosted with ❤ by GitHub

With this example, you will have:

	// As 2 objects
	var pluginScriptExtStrings = {
	firstLabel: 'Some string to translate', // localized
	secondLabel: 'Some string to translate', // localized
	};
	var pluginScriptExtConfig = {
	something: 'some-value',
	somethingElse: 3
	};

view raw wpPluginScriptExt.js hosted with ❤ by GitHub

It is important to note that the script should either be registered (via wp_register_script) or enqueued (via wp_enqueue_script) before it can be localized.

Initializing Scripts

There are several scripts, like sliders, that require some sort of initialization. Take waypoints, for example. It requires initialization before it can be used on the page. For example:

	var waypoint = new Waypoint({
	element: document.getElementById('waypoint'),
	handler: function(direction) {
	console.log('Scrolled to waypoint!')
	}
	});

view raw wp-waypoint-init.js hosted with ❤ by GitHub

To do this properly within WordPress, you need to use wp_add_inline_script.

	<?php

	namespace MyPrefix\MyPlugin;

	define( 'MY_PLUGIN_VERSION', '1.0.0' );

	add_action( 'init', __NAMESPACE__ . '\register_scripts' );
	/**
	* Register my frontend scripts.
	*/
	function register_scripts() {

	if ( is_admin() ) {
	return;
	}

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	// Assumes the JS file is located in the js folder within the plugin folder.
	wp_register_script(
	'waypoints',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/waypoints{$suffix}.js", // file URL
	array(), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/waypoints{$suffix}.js" ), // version
	true
	);

	wp_register_script(
	'my-waypoints',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/my-waypoints{$suffix}.js", // file URL
	array( 'waypoints' ), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/my-waypoints{$suffix}.js" ), // version
	true
	);

	}

	add_action( 'wp_enqueue_scripts', __NAMESPACE__ . '\wp_enqueue_scripts' );
	/**
	* Register my scripts.
	*/
	function wp_enqueue_scripts() {

	wp_enqueue_script( 'my-waypoints' );
	wp_add_inline_script( 'my-waypoints', "var waypoint = new Waypoint({
	element: document.getElementById('waypoint'),
	handler: function(direction) {
	console.log('Scrolled to waypoint!')
	}
	})" );

	}

	// Result
	//<script type="text/javascript" src="https://domain.com/wp-content/plugins/myplugin/js/my-waypoints.js"></script>
	//<script type="text/javascript">
	// var waypoint = new Waypoint({element: document.getElementById('waypoint'),
	// handler: function(direction) {
	// console.log('Scrolled to waypoint!')
	// }
	// })
	//</script>

view raw wp-add-inline-script-plugin.php hosted with ❤ by GitHub

wp_add_inline_script can also output JavaScript before a specific script tag. To do this:

	<?php

	namespace MyPrefix\MyPlugin;

	define( 'MY_PLUGIN_VERSION', '1.0.0' );

	add_action( 'init', __NAMESPACE__ . '\register_scripts' );
	/**
	* Register my frontend scripts.
	*/
	function register_scripts() {

	if ( is_admin() ) {
	return;
	}

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	// Assumes the JS file is located in the js folder within the plugin folder.
	wp_register_script(
	'waypoints',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/waypoints{$suffix}.js", // file URL
	array(), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/waypoints{$suffix}.js" ), // version
	true
	);

	wp_register_script(
	'my-waypoints',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/my-waypoints{$suffix}.js", // file URL
	array( 'waypoints' ), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/my-waypoints{$suffix}.js" ), // version
	true
	);

	}

	add_action( 'wp_enqueue_scripts', __NAMESPACE__ . '\wp_enqueue_scripts' );
	/**
	* Register my scripts.
	*/
	function wp_enqueue_scripts() {

	wp_enqueue_script( 'my-waypoints' );
	wp_add_inline_script( 'my-waypoints', 'console.log("before my-waypoints file")', 'before' );

	}

	// Result
	//<script type="text/javascript">
	// console.log("before my-waypoints file")
	//</script>
	//<script type="text/javascript" src="https://domain.com/wp-content/plugins/myplugin/js/my-waypoints.js"></script>

view raw wp-add-inline-script-plugin-before.php hosted with ❤ by GitHub

If you use wp_localize_script and wp_add_inline_script, wp_localize_script will always output before wp_add_inline_script.

Using wp_add_inline_script is a great way to keep your code clean using native WordPress functions and the script manager avoiding yet another hook and manually outputting this yourself.

It is important to note that the script should either be registered (via wp_add_inline_script) or enqueued (via wp_add_inline_script) before it can be initialized.

Extending the previous Waypoints example, let's only do something if waypoints is not already registered. You do this by using wp_script_is.

	<?php

	namespace MyPrefix\MyPlugin;

	define( 'MY_PLUGIN_VERSION', '1.0.0' );

	add_action( 'init', __NAMESPACE__ . '\register_scripts' );
	/**
	* Register my scripts.
	*/
	function register_scripts() {

	// Do nothing if the script is registered
	if ( wp_script_is( $handle, 'registered' ) ) {
	return;
	}

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	// Assumes the JS file is located in the js folder within the plugin folder.
	wp_register_script(
	'waypoints',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/waypoints{$suffix}.js", // file URL
	array(), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/waypoints{$suffix}.js" ), // version
	true
	);

	}

view raw wp-scripts-is.php hosted with ❤ by GitHub

With wp_script_is, you can check whether a script has been:

registered
enqueued/queued
to_do/to_print
done/printed

wp_script_is is quite powerful in debugging scripts and in trying to find when a script was registered, enqueued, and printed on the page.

For example, with wp_script_is( $handle, 'enqueued' ), you can know that you can either deregister (if false) or dequeue the script (if true) in order to prevent that script from being printed on the page.

Finally (though this is becoming much less important), you can make your scripts conditional by adding conditional data to the script. You can do this by using

	<?php

	namespace MyPrefix\MyPlugin;

	define( 'MY_PLUGIN_VERSION', '1.0.0' );

	add_action( 'init', __NAMESPACE__ . '\register_scripts' );
	/**
	* Register my frontend scripts.
	*/
	function register_scripts() {

	if ( is_admin() ) {
	return;
	}

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	// Assumes the JS file is located in the js folder within the plugin folder.
	wp_register_script(
	'plugin-script',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/plugin-script{$suffix}.js", // file URL
	array(), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/plugin-script{$suffix}.js" ), // version
	true
	);

	// IE only Script
	wp_register_script(
	'plugin-script-ie',
	get_plugin_dir( MY_PLUGIN_FILE ) . "js/plugin-script-ie{$suffix}.js", // file URL
	array( 'plugin-script' ), // dependencies
	MY_PLUGIN_VERSION . '-' . filemtime( plugin_dir_url( MY_PLUGIN_FILE ) . "js/plugin-script-ie{$suffix}.js" ), // version
	true
	);

	}

	add_action( 'wp_enqueue_scripts', __NAMESPACE__ . '\wp_enqueue_scripts' );
	/**
	* Register my scripts.
	*/
	function wp_enqueue_scripts() {

	wp_enqueue_script( 'plugin-script' );
	wp_script_add_data( 'plugin-script', 'conditional', 'lt IE 9' );

	}

view raw wp-conditional-scripts.php hosted with ❤ by GitHub

Modifying Script Tags on Print

Adding Additional Attributes to `script` tag—`async` and `defer`

WordPress does not automatically add async or defer to your script tags, nor is there an "easy" way to add it to the script manager (which is still being actively discussed in core (tickets 22249 and 12009).

First, what is the difference between defer and async? bitsofcode has two great diagrams that explains the difference between the two:

Simply stated both defer and async download/fetch the script immediately and do not pause/prevent further HTML parsing. The difference comes at JavaScript execution. defer executes after the HTML parsing is completed and DOM is ready. Because of this adding defer to scripts in the footer makes little sense. async executes when the script comes ready.

To improve the performance of the page, you need to add these yourself. You can do this by using the script_loader_tag filter, which gives you the HTML of the script being printed on the page, including the conditional HTML and any added inline script.

To add async or defer to all, you can do this:

	<?php

	namespace MyPrefix\MyTheme;

	add_filter( 'script_loader_tag', __NAMESPACE__ . '\script_loader_tag_add_async', 10 );
	/**
	* Filters the HTML script tag of an enqueued script.
	*
	* @param string $tag The `<script>` tag for the enqueued script.
	* @param string $handle The script's registered handle.
	* @param string $src The script's source URL.
	*
	* @return string Modified script tags including `async="async"`.
	*/
	function script_loader_tag_add_async( $tag ) {

	if ( false === strpos( $tag, 'async' ) ) {
	return str_replace( ' src', ' async="async" src', $tag );
	}

	}

	add_filter( 'script_loader_tag', __NAMESPACE__ . '\script_loader_tag_add_defer', 10 );
	/**
	* Filters the HTML script tag of an enqueued script.
	*
	* @param string $tag The `<script>` tag for the enqueued script.
	* @param string $handle The script's registered handle.
	* @param string $src The script's source URL.
	*
	* @return string Modified script tags including `async="async"`.
	*/
	function script_loader_tag_add_defer( $tag ) {

	if ( false === strpos( $tag, 'defer' ) ) {
	return str_replace( ' src', ' defer="defer" src', $tag );
	}

	}

view raw wp-scripts-cache-async-all.php hosted with ❤ by GitHub

Alternatively, you can be more specific and do something like this:

	<?php

	namespace MyPrefix\MyTheme;

	add_filter( 'script_loader_tag', __NAMESPACE__ . '\script_loader_tag', 10 );
	/**
	* Filters the HTML script tag of an enqueued script.
	*
	* @param string $tag The `<script>` tag for the enqueued script.
	* @param string $handle The script's registered handle.
	* @param string $src The script's source URL.
	*
	* @return string Modified script tags including `async="async"`.
	*/
	function script_loader_tag( $tag ) {
	// Load AFTER a page has finished loading completely
	$deferred = array( 'comment-reply', 'wp-emoji' );
	foreach ( $deferred as $script ) {
	if ( false !== strpos( $tag, $script ) && false === strpos( $tag, 'defer' ) ) {
	return str_replace( ' src', ' defer="defer" src', $tag );
	}
	}

	// Load asynchronously while page is loading
	$async = array( 'wp-embed', 'myscript' );
	foreach ( $async as $script ) {
	if ( false !== strpos( $tag, $script ) && false === strpos( $tag, 'async' ) ) {
	return str_replace( ' src', ' async="async" src', $tag );
	}
	}

	return $tag;
	}

view raw wp-scripts-cache-async-defer.php hosted with ❤ by GitHub

If you use the Genesis Framework, this is already built-in for you. All you need to do is register your script with either ?async=true or ?defer=true and Genesis will automagically add async or defer to the script tag for you!!

	<?php

	namespace MyPrefix\MyTheme;

	define( 'MY_THEME_VERSION', '1.0.0' );

	add_action( 'init', __NAMESPACE__ . '\register_scripts' );
	/**
	* Register my scripts.
	*/
	function register_scripts() {

	// Suffix
	$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';

	// Assumes the JS file is located in the js folder within the theme folder.
	wp_register_script(
	'myscript', // file slug
	get_stylesheet_directory_uri() . "/js/myscript$suffix.js?defer=true", // file URL with ?async=true added
	array(), // dependencies
	MY_THEME_VERSION . '-' . filemtime( get_stylesheet_directory() . "/js/myscript$suffix.js" ), // version
	true // in footer or not
	);

	wp_register_script(
	'jquery-myscript', // file slug
	get_stylesheet_directory_uri() . "/js/jquery.myscript$suffix.js?async=true", // file URL with ?defer=true added
	array( 'jquery' ), // dependencies
	MY_THEME_VERSION . '-' . filemtime( get_stylesheet_directory() . "/js/jquery.myscript$suffix.js" ), // version
	true // in footer or not
	);

	}

view raw wp-register-genesis-theme-script.php hosted with ❤ by GitHub

Changing the Script Source—Cache Busting

You can use the script_loader_src filter to cache bust everything.
DO NOT USE THIS IN PRODUCTION.

	<?php

	namespace MyPrefix\MyTheme;

	add_filter( 'script_loader_src', __NAMESPACE__ . '\script_loader_src', 10, 2 );
	/**
	* Cache bust all the scripts.
	*
	* @param string $src Script loader source path.
	* @param string $handle Script handle.
	*
	* @return string
	*/
	function script_loader_src( $src, $handle ) {
	if ( 'plugin-script' !== $handle ) {
	return $src;
	}

	return add_query_arg( 'wps', time(), $src );
	}

view raw wp-scripts-cache-bust-all.php hosted with ❤ by GitHub

Summary

With this overview of the native WordPress Script functions for script management, you should be able to use any type of JavaScript file in any plugin or theme extending parent theme or plugin JavaScript files.

PHP Constants for Debugging JavaScript: SCRIPT_DEBUG allows you to manage whether your script outputs minified or not. You can also pass the value of SCRIPT_DEBUG to wp_localize_script to help you add debug messages within the console.
Registering and Deregistering Scripts: Use wp_register_script to register a script on init hook and wp_deregister_script only if you plan to register an alternative to avoid any unintended effects.
Enqueueing and Dequeueing Scripts: Use wp_enqueue_script to output the script on the page and wp_dequeue_script to prevent the script's output.
Localizing Scripts: Use wp_localize_script to output any configuration and translations of any strings used within your script.
Initializing Scripts: Use wp_add_inline_script to add additional inline scripts to initialize external scripts or any thing else than adding a configuration object.
Modifying Script Tags on Print: Use script_loader_src and script_loader_tag to make more advanced changes to the script tag including adding attributes like async or defer, which Genesis makes easy for you.

Thank you to both Gary Jones and Mike Hemberger for pre-reviewing and providing some great insights!

Mar 03 2014

Beginner Developer Series: Setting Up a Local Environment via XAMPP (Apache, PHP, mySQL)

When developing, it is always good to have a local site. Many skip this and use only a staging site and the production site. However, having a local environment will make life easy with testing scripts quickly and easily. Change a file, save, and run. However, using a staging site, you have to FTP up and down, and with WordPress and Windows, this sometimes can get you into trouble if not done correctly.

So, we need to install Apache (the server software), PHP (the language that WordPress runs on), and MySQL (the database). To do this on an Apple machine, use the Make WordPress Tutorial for MAMP or see the older tutorial in the Codex: Installing MAMP. For Windows machines, there is XAMPP, which stands for Apache + MySQL + PHP + Perl.

Quick Summary

Here are the simplified steps on how to install WordPress on your local computer that we will walk through this week:

Install a local server ( XAMPP).
Configure PHP
Launching Apache & Troubleshooting with Skype
Create a new database via phpMyAdmin.
Setup XAMPP Security
Download WordPress from wordpress.org and install into the htdocs folder (typically C:/xampp/htdocs).
Run the famous 5 minute install and follow the instructions: wp-admin/install.php.
Done!

Dec 22 2011

How to Add a Custom Field Shortcode to Use Any Custom Field in Posts

In another tutorial I am writing, one for non-coders, I needed a way to pull in custom fields into the post. Currently (and sadly), in Genesis there is no way to do this; however, Genesis does have a great php function that already does this, genesis_get_custom_field(). So turning that into a shortcode is rather easy. Just add the following to your functions.php code:

[php]
add_shortcode( 'post_field', 'genesis_post_field_shortcode' );
/**
* Returns the value of a custom field.
*
* Supported shortcode attributes are:
* field (field name),
*
* @param array $atts Shortcode attributes
* @return string Shortcode output
*/
function genesis_post_field_shortcode( $atts ) {

$defaults = array(
'field' => '',
);
$atts = shortcode_atts( $defaults, $atts );

return genesis_get_custom_field( $atts['field'] );
}
[/php]
To use the shortcode, you just insert [ post_field field="my_field_name"] (without the space in the front) and boom! It works!

Dec 12 2011

Filter Pages by Post Parent and Filter Pages/Posts by Pages/Posts Per on WordPress Edit Pages

Recently I migrated a site that had hundreds of pages, which made page management a potential nightmare. Seeing this potential, I developed a filter that would enable me to see various parts of the pages tree as well as allow me to set the number of pages I wanted to see.

To add a filter on the edit page, you must hook into 'restrict_manage_posts'. The function below will add 2 filters: pages_per filter and a post_parent page filter. The pages_per filter is something that can be used on all post types; however, the post_parent filter should only be used on pages (or other hierarchical post types--but for this tutorial, we will only do pages).

So here's what I did:
[php]
add_action ( 'restrict_manage_posts' , 'wps_restrict_manage_posts' );
function wps_restrict_manage_posts() {
global $typenow;

// only run this filter on page post type
if ( $typenow == 'page' ) {

// Parent Page Filter (HTML)
$args = array(
'child_of' => 0,
'show_option_none' => 'Show all pages',
'depth' => 2, //change this to whatever you want
'name' => 'wps_page_filter',
'selected' => $_GET['wps_page_filter'],
);
$dropdown = wp_dropdown_pages( $args );
}

// Per Page Filter (HTML)
global $wps_per_page;
$wps_per_page = isset( $_GET['wps_per_page'] ) ? (int) $_GET['wps_per_page'] : $wps_per_page;
?>
<select name="wps_per_page" style="width: 110px;">
<option <?php selected( $wps_per_page, 9999 ); ?> value="9999"><?php _e( 'Show all', FDA_DOMAIN ); ?></option>
<?php for( $i=10; $i<=100; $i+=10 ) : ?>
<option <?php selected( $wps_per_page, $i ); ?> value="<?php echo $i; ?>"><?php echo $i; ?> <?php _e( 'per page', FDA_DOMAIN ); ?></option>
<?php endfor; ?>
<?php if ( $wps_per_page != -1 && $wps_per_page != 9999 && ( $wps_per_page%10 != 0 || $wps_per_page > 100 ) ) : ?>
<option <?php selected( true ); ?> value="<?php echo (int) $wps_per_page; ?>"><?php echo (int) $wps_per_page; ?> <?php _e( 'per page', FDA_DOMAIN ); ?></option>
<?php endif; ?>
</select>
<?php
}
[/php]

Now, I wanted to add an option to show only top level pages only. This has to be done manually, darn WordPress for having no good filters in wp_dropdown_pages().
[php]
// Add an option to show top level pages only
add_filter ( 'wp_dropdown_pages' , 'wps_insert_option_in_dropdown' );
function wps_insert_option_in_dropdown ( $output ) {
$filter = $_GET['wps_page_filter'];
if ( $filter == 'parent' )
$selected = ' selected="selected"';
else
$selected = '';
$second_option = 'Show all pages</option><option value="parent"' . $selected . '>Parent Pages Only</option>';
return preg_replace( '#Show all pages</option>#' , $second_option , $output );
}
[/php]

Now, WordPress won't execute the filter for us, so we have to make sure this happens. This can be done in two separate functions; however, since it really doesn't matter pragmatically, we will keep with one function.
[php]
add_filter ( 'parse_query', 'wps_admin_posts_filter' );
function wps_admin_posts_filter( $query ) {
global $pagenow;

// Update pages_per (just because we are here, we do it in this function)
$wps_per_page = $_GET['wps_per_page'];
if ( isset( $wps_per_page ) && ( $wps_per_page == 9999 || ( $wps_per_page % 10 ) == 0 ) )
update_user_option( get_current_user_id(), 'edit_page_per_page', (int) $wps_per_page );

// Change query based on post_parent
$wps_page_filter = $_GET['wps_page_filter'];
if ( is_admin() && $pagenow == 'edit.php' && !empty( $wps_page_filter ) ) {
if ( $wps_page_filter == 'parent' )
$query->query_vars['post_parent'] = 0;
else
$query->query_vars['post_parent'] = $wps_page_filter;
}
}
[/php]

Setup

Custom Post Type / Taxonomy Example

Setup

Doing the Rewrites

On Activation

Taxonomy / Custom Post Type Example

Setup

Doing the Rewrites

On Activation

Prefix / Custom Post Type Example

Setup

Doing the Rewrites

On Activation

Wrap-Up

PHP Constants for Debugging JavaScript

Registering and Deregistering Scripts

DRY

Client Focused & Client Friendly

Integrations & Prevents Duplication

The Code: Registering/Deregistering Scripts

Registering JavaScript Files

Script Version ($ver)

Script Dependencies ($deps)

Registering Scripts in Themes

Registering Scripts in Plugins

Deregistering JavaScript Files

A Note

Enqueueing and Dequeueing Scripts

Localizing Scripts

Initializing Scripts

Modifying Script Tags on Print

Adding Additional Attributes to script tag—async and defer

Changing the Script Source—Cache Busting

Summary

Quick Summary

Script Version (`$ver`)

Script Dependencies (`$deps`)

Adding Additional Attributes to `script` tag—`async` and `defer`