New theme URL and theme path functions in WordPress 4.7

With WordPress 4.7, the core has received four new functions for returning the theme URL or theme path, which complement and partially replace the old functions. In this post I introduce the new possibilities.

For a better understanding, I recommend reading my post from last week, in which I introduced the previous URL and file path functions for theme developers .

The problem with the well-known functions is that, depending on the function, either the URL / path of the parent theme or the child theme was returned. This made it impossible to overwrite files in a child theme, as is possible with template files and get_template_part (), for example.

For this reason, new functions were introduced with WordPress 4.7 .

get_theme_file_uri

With the new function get_theme_file_uri () , the URL to the theme folder is returned, similar to get_template_directory_uri and get_stylesheet_directory_uri . The typical use case in the WordPress theme is therefore the integration of CSS and JavaScript.

The new thing about the function is that with the use of get_theme_file_uri it is checked whether the file exists in the child theme. If not, the file in the parent theme is used as a fallback.

To do this, the relative path to the file in the theme folder is passed as a parameter, and not appended as a string as before. As a return we get a URL directly to the file, which is why the function has its name ( file instead of directory ).

 wp_enqueue_script( 'custom-script', get_theme_file_uri( 'js/custom-script.js' ) );

First, an attempt is made to integrate the custom-script.js file from the child theme. If this does not exist in the child theme, the file in the parent theme is used automatically.

It is now possible for theme developers to make JavaScript and CSS files overwritable by integrating them with the new get_theme_file_uri function instead of get_template_directory_uri () as before.

Users of the theme can simply copy the CSS / JS files from the parent theme to the child theme and make changes there to overwrite the original file - just as it has been working for template files for a long time.

get_theme_file_path

Similar to the new function for the theme file URL, there is also a function for returning the theme file path: get_theme_file_path ()

This works the same way. The file is passed as a parameter and, depending on the existence of the file, the path to the child or parent theme is returned.

In principle, the function can therefore be used to load PHP files so that they can be overwritten in a child theme.

 require get_theme_file_path( '/inc/customizer.php' );

But I advise against that.

The existing and special functions such as get_template_part () should always be used to load template files.

And function files like template-tags.php or customizer.php should n't be able to be overwritten with a child theme in my opinion. Any updates to the files in the parent theme would be lost, which can ultimately lead to problems. For example, if functions are added or changed by updating the parent theme.

Instead of completely overwriting entire files with many functions, it is better to modify the individual functions in the child theme using appropriate hooks and filters.

But the function is not useless. A possible use case is already shown in the announcement post:

 wp_enqueue_script( 'custom-script', get_theme_file_uri( 'js/custom-script.js' ), array(), filemtime( get_theme_file_path( 'js/custom-script.js' ) ) );

With the help of filemtime, the version number for the JavaScript file is automatically generated dynamically based on the last processing date . Here the absolute path to the file is required, which get_theme_file_path provides us.

Functions for the parent theme folder

In addition to these two new functions, get_parent_theme_file_uri () and get_parent_theme_file_path () have also introduced two functions for returning the theme file URL and the theme file path for files in the parent theme folder.

These are intended to replace get_template_directory and get_template_directory_uri . Technically, they offer no innovations and serve the same purpose.

They are used like the get_theme_file_ * functions, ie the file is passed as a parameter. The return is not the parent theme folder, but the URL / path directly to the file.

get_parent_theme_file_path

Suitable for loading function files in the parent theme.

The following line with the old implementation

 require get_template_directory() . '/inc/customizer.php';

corresponds to the line

 require get_parent_theme_file_path( '/inc/customizer.php' );

using the new function.

get_parent_theme_file_uri

In order to incorporate CSS or JavaScript of the parent theme without allowing the files to be overwritten , the new function can now be used instead of get_template_directory_uri :

 wp_enqueue_script( 'customize-controls', get_parent_theme_file_uri( '/js/customize-controls.js' ) );

Conclusion

I like the new features.

The names describe the functions in a much more understandable way, which should improve the confusing difference between stylesheet and template directory in particular. I also find the implementation with function and parameters more readable than the previous link between function and file name as a text string.

TwentySeventeen is already fully relying on the new functions. Since the default themes usually set the benchmark and best practices in theme development, we will probably see the new functions more often in the future.

The biggest disadvantage at the moment is that these are only available with WordPress 4.7. One of the reasons that TwentySeventeen does not work with earlier WordPress versions. If the theme should still run with WordPress 4.6 and earlier, the old functions must still be used.