Template tag: wp_include_file

[KKWangen]

This is related to changeset r8497 that let you override the templates of a Parent Theme in a Child Theme.

But if a theme uses the code:

<?php include (TEMPLATEPATH . '/file.php'); ?>

to include misc. template files, you can not override that file in Child Theme.

So I thought it might be a better idea to have template tag for including misc. template files in a theme, so they can be overridden in a child theme.

The code I've played with to make it work looks like this:

function wp_include_file($name = '', $dir = '') {
	$file = "{$name}.php";
	$include = apply_filters("include_{$name}", STYLESHEETPATH . "{$dir}/{$name}.php" );

	if ( file_exists( $include) )
		include( $include);
	elseif ( file_exists( TEMPLATEPATH . "{$dir}/{$name}.php") )
		include( TEMPLATEPATH . "{$dir}/{$name}.php");
}

$name is the name of the file without the .php, so to include searchform.php you get a code like:

<?php wp_include_file('searchform'); ?>

the $dir variable will let theme authors put the misc template files they in subdirectory of their theme's root directory.

Example: a theme author add their searchform.php file in a /includes subdirectory. Then they can include the file in the theme with:

<?php wp_include_file('searchform','/includes'); ?>

To override the file in a Child Theme, you can either add it in using the same structure as the Parent Theme: /childtheme/includes/searchform.php

Or you can filter the path in the Child Theme's function php file:

function my_searchform() { 
$my_searchform = STYLESHEETPATH . '/searchform.php';
return $my_searchform;
}
add_filter('include_searchform','my_searchform');

[jacobsantos]

I have this in my custom applications. I don't like it being in WordPress, because conditional including is slower than just plain including what you need. For themes, I don't think it makes a great deal of sense. You should know exactly what you are going to include.

When it comes to themes WordPress doesn't always know what you mean and what should be loaded. In that case, it is better for conditional loading. It would be good to include the API in your themes functions.php file, if you want it.

[jacobsantos]

No patch. Moving to 2.9, until core devs consider it.

[westi]

Note sure how this might work well...

I will have a think on this though.

[KKWangen]

I do have a similar code in my themes, but I thought it might be better to have the functionality in the core of WordPress so everyone can benefit from it.

There are other possible usage of this code;
because the code checks if the file you want to include is current, a theme author may add support for a navigation bar on top of their theme, by adding the code to their header.php:

<?php wp_include_file('navbar'); ?>

So if a user of the theme wants a navigation bar, s/he only have to create the file navbar.php with the code s/he want and add it to the theme. And if they don't want it anymore, they can just delete the file without the theme breaking.

• I know several themes uses filters for this, but by experience most theme users are not that happy with writing php functions to make a theme work for them.

I do think WordPress needs some kind of function to deal with misc. template files, because when WP 2.7 comes along, theme authors will encourage theme users to make child themes if they want to customize the theme. And theme authors will tell that all template files can be overridden in the child theme.

But an end user of a theme do not know which files that's WordPress standard template files and which is misc. template files created/ added by the theme author.

So if someone tries to customize the WordPress default theme by creating a child theme of it, they will ask and wonder why searchform.php can't be overridden like all the other template files.

But; if you think it's a bad idea to have this functionality/ template tag in WordPress core, and it rather should be something added to a theme's functions.php file, that's okay with me.

I just think it would be easier for everyone, - and especially for theme authors who's not very familiar with writing own functions for their themes.

[santosj]

My argument is only performance related. What you discuss is something that will be needed. A patch will not be difficult and yeah, if performance is required, the theme author doesn't have to use the function.

[westi]

(In [8624]) Refactor template location code to reduce duplication.
Also make it easier for theme authors to pull in seperate files into templates while making theme overrideable. See #7492.

[westi]

Ok that should enable you to do what you want.

We can probably make locate_template a little more friendly (and maybe it needs a better name).

At present you would put the following in your theme:

   locate_template(array('navbar.php'),true);

This will search for the file in the correct locations for your theme and then include it in using load_template so that it gets all the globals setup correctly.

[santosj]

For the name: wp_load_theme_file() or load_theme_file() or theme_file_include().

[KKWangen]

This works great, but:

I think it should be possible to filter the path to file, as you can do that with mostly all other template files. As WordPress is to day, I'm able to have global 404.php file that all themes use, because I can filter the path to the file.

So it could be good to have this option for misc. files as well, as this would give me the option to have global navbar.php that all themes that have support for it uses.

There was another problem with the code as well:

Some themes include the same files several places in the theme, like the searchform.php file are included in sidebar.php, in 404.php and sometimes in a custom archive page template (the default theme does this), but because load_template() is doing require_once, the search form disappears from the sidebar when the 404 template or the archive page template are loaded.

I'm not sure how to deal with that. Could it be possible to set a third parameter to the code? like:

function locate_template($template_names, $load = false, $include = false)

And if $include = true, the misc. template uses include($located) instead of load_template($located)

This is just a on the top of head idea;

But I think it's right to have the misc. files to only be included once by default, in case you mess up and writes the wrong filename, and try to load for example navbar.php in the sidebar as well as in header.php

I'm not sure about what name to give the function, it has to be something "terrible" logic, like the other template tags are:

wp_load_theme_file() might work, or maybe wp_include_template, wp_get_template, wp_template?

[KKWangen]

I've played around a little with the code today and thought that it might be more useful make the function pluggable instead of having a filter for the path to the files.

This would allow me to just write up one function to allow me to have global template files with just one function instead of several like I have now.

[jacobsantos]

get_query_template() seems to solve this.

[jacobsantos]

include( get_query_template('searchform') )

I don't think abstracting include in another function is a good idea because of the additional overhead.