Custom scripts handle names in WordPress

While doing some support for my WordPress plugins I noticed there was a conflict going on with Dynamic To Top and another developer’s plugin. To make it short, we used the same jQuery plugin but registered it with different handle names. A dumb little issue but it was actually breaking our plugins.

You probably seen this happen a lot, some uses dashes (-) others dots (.) other underscores (_). Here are some of the most common variations I came across which have no standardization other than being lowercase strings:

wp_enqueue_script('jquery-easing' ...);
wp_enqueue_script('jquery_easing' ...);
wp_enqueue_script('jqueryeasing' ...);
wp_enqueue_script('jquery.easing' ...);
wp_enqueue_script('easing' ...);

This is a big problem as it will result in the same script (not the same file) being loaded twice and sometimes like in this case, cause a JavaScript conflict rendering your plugins useless.

Looking trough the Codex I noticed the custom scripts examples used to show underscores and the list of core bundled scripts dashes. That probably helped to create confusion.

I wanted to be sure I was doing_it_right, so I went straight to the source and asked core developer Andrew Nacin what he thought:

He suggested to use dashes and also encouraged me to update the Codex examples, which I did and that is something that deserves a separate post as it’s really easy to contribute and we should be doing it more.

Back to the handlers, if you are using a library plugin, then you should care about the name composition too. Try to use the library name first and then the plugin/extension just like core does it:

wp_enqueue_script('library-plugin' ...);
wp_enqueue_script('jquery-easing' ...);

Remember to keep this suggestion in mind for your next theme/plugin. Hopefully it will help us all prevent some issues in the future,

Thanks for reading!

Reactions (2)

  1. Nice catch, Matt. But even better, thanks for understanding and helping fix the problem after finding it! I wish we were all so diligent (I’m often not). So, +1 point for you, sir.

  2. Nice highlight for developer’s.

    Going along the same lines, dev’s should avoid adding js, script, css or style suffixes when they enqueue scripts are styles, as WP already adds it’s own suffix.