The Quick Start Guide To WordPress URLs and Paths: How To Include Scripts and Files

One thing that confuses a lot of WordPress theme designers and plugin developers is including files, templates, and javascript libraries. The official documentation has all the information but looking at the number of themes and plugins who get it so wrong I think it’s not well structured.


Don’t worry. This guide will clear it up. It is surprisingly short but still gives you everything you need to know. So spend a few minutes to read it and bookmark it for future use.

There are three main areas which confuse developers: how to create links to other pages in the site; how to properly include scripts and CSS files; and how to properly include files with your code libraries. Let’s dissect them:

Create URLs to the site

When creating internal links, for example in the admin area, you need no special function. Simply use “admin.php?page=…” in your links.

Sometimes you need to create links to admin pages which will be sent in automated emails etc. In this case you will need the full URL of the administration. Do not use “wp-admin” because some webmasters customize their installations and rename the administration folder.

The proper function to use here is admin_url. For example admin_url(“admin.php?page=my_theme_config”);

Similarly to create a link to front-end page use the function site_url.

Have  a quick look also on the “Related” sections on the above linked documentation pages. Usually these two functions are all you need, but sometimes the other functions may come handy.

Include CSS files and Scripts

I can’t count the number of themes and plugins that hardcode paths to javascript and CSS files. In the best case this leads to non-loading files, and other times it leads to conflicts with multiple jquery versions loaded.

You must always use wp_enqueue_script and wp_enqueue_style instead of hardcoding calls in your themes and plugins. With libraries that are included in the WordPress installation, like jQuery, things are super easy. You only need to call:

wp_enqueue_script('jquery');

And you are all set. When including your own scripts you have to use wp_register_script() first.

In this case the plugins_url should be called to get the full path of where you script is. Let’s have a quick full example of including a custom script. In plugins this should happen in the function which you call on the “wp_enqueue_scripts” or “admin_enqueue_scripts” action:

wp_enqueue_script(
'myplugin-script',
plugins_url('/myplugin/lib/main.js'),
array(),
'1.0');

In the next section read how to remove the hardcoded “myplugin” part. This could be useful if someone decides to rename your plugin folder for some reason.

Include Files With Code

Finally, when including libraries with code you should find the server path where your files are. Here is what I recommend in this case:

define( 'MYPLUGIN_PATH', dirname( __FILE__ ) );
define( 'MYPLUGIN_RELATIVE_PATH', dirname( plugin_basename( __FILE__ )));
define( 'MYPLUGIN_URL', plugin_dir_url( __FILE__ ));

Defining these constants in your main plugin file will ensure you can use them anywhere in the other files inside your plugin or theme code. Please do not use MYPLUGIN as prefix. Use something specific for your plugin so it won’t interfere with someone else’s constants.

The first constant – MYPLUGIN_PATH – is used when including one file in another file, for example a library with some functions:

include(MYPLUGIN_PATH."/lib/functions.php");

The second constant – MYPLUGIN_RELATIVE_PATH – is used a lot less – only when you need a relative path. One such example is loading plugin’s textdomain:

load_plugin_textdomain( 'myplugin', false, MYPLUGIN_RELATIVE_PATH."/languages/" );

The third constant – MYPLUGIN_URL – is actually useful for including scripts and CSS files as explained in the previous section. Instead of hardcoding your plugin folder in the wp_enqueue_script call you can use this constant.

Finally, if you allow the end user to design their own themes for custom post type or something like that, use get_stylesheet_directory. That’s it.

There are a lot more URL and path related functions in WordPress. But in 99% of the cases the ones listed here are all you need. Learn about them and use them. Don’t be one of those plugin and theme authors who hardcode jquery versions and paths containing “wp-admin” in them.

 

Share Your Thoughts

*