WordPress 3.4
[autoinstalls/wordpress.git] / wp-includes / template.php
1 <?php
2 /**
3  * Template loading functions.
4  *
5  * @package WordPress
6  * @subpackage Template
7  */
8
9 /**
10  * Retrieve path to a template
11  *
12  * Used to quickly retrieve the path of a template without including the file
13  * extension. It will also check the parent theme, if the file exists, with
14  * the use of {@link locate_template()}. Allows for more generic template location
15  * without the use of the other get_*_template() functions.
16  *
17  * @since 1.5.0
18  *
19  * @param string $type Filename without extension.
20  * @param array $templates An optional list of template candidates
21  * @return string Full path to file.
22  */
23 function get_query_template( $type, $templates = array() ) {
24         $type = preg_replace( '|[^a-z0-9-]+|', '', $type );
25
26         if ( empty( $templates ) )
27                 $templates = array("{$type}.php");
28
29         return apply_filters( "{$type}_template", locate_template( $templates ) );
30 }
31
32 /**
33  * Retrieve path of index template in current or parent template.
34  *
35  * @since 3.0.0
36  *
37  * @return string
38  */
39 function get_index_template() {
40         return get_query_template('index');
41 }
42
43 /**
44  * Retrieve path of 404 template in current or parent template.
45  *
46  * @since 1.5.0
47  *
48  * @return string
49  */
50 function get_404_template() {
51         return get_query_template('404');
52 }
53
54 /**
55  * Retrieve path of archive template in current or parent template.
56  *
57  * @since 1.5.0
58  *
59  * @return string
60  */
61 function get_archive_template() {
62         $post_type = get_query_var( 'post_type' );
63
64         $templates = array();
65
66         if ( $post_type )
67                 $templates[] = "archive-{$post_type}.php";
68         $templates[] = 'archive.php';
69
70         return get_query_template( 'archive', $templates );
71 }
72
73 /**
74  * Retrieve path of author template in current or parent template.
75  *
76  * @since 1.5.0
77  *
78  * @return string
79  */
80 function get_author_template() {
81         $author = get_queried_object();
82
83         $templates = array();
84
85         $templates[] = "author-{$author->user_nicename}.php";
86         $templates[] = "author-{$author->ID}.php";
87         $templates[] = 'author.php';
88
89         return get_query_template( 'author', $templates );
90 }
91
92 /**
93  * Retrieve path of category template in current or parent template.
94  *
95  * Works by first retrieving the current slug for example 'category-default.php' and then
96  * trying category ID, for example 'category-1.php' and will finally fallback to category.php
97  * template, if those files don't exist.
98  *
99  * @since 1.5.0
100  * @uses apply_filters() Calls 'category_template' on file path of category template.
101  *
102  * @return string
103  */
104 function get_category_template() {
105         $category = get_queried_object();
106
107         $templates = array();
108
109         $templates[] = "category-{$category->slug}.php";
110         $templates[] = "category-{$category->term_id}.php";
111         $templates[] = 'category.php';
112
113         return get_query_template( 'category', $templates );
114 }
115
116 /**
117  * Retrieve path of tag template in current or parent template.
118  *
119  * Works by first retrieving the current tag name, for example 'tag-wordpress.php' and then
120  * trying tag ID, for example 'tag-1.php' and will finally fallback to tag.php
121  * template, if those files don't exist.
122  *
123  * @since 2.3.0
124  * @uses apply_filters() Calls 'tag_template' on file path of tag template.
125  *
126  * @return string
127  */
128 function get_tag_template() {
129         $tag = get_queried_object();
130
131         $templates = array();
132
133         $templates[] = "tag-{$tag->slug}.php";
134         $templates[] = "tag-{$tag->term_id}.php";
135         $templates[] = 'tag.php';
136
137         return get_query_template( 'tag', $templates );
138 }
139
140 /**
141  * Retrieve path of taxonomy template in current or parent template.
142  *
143  * Retrieves the taxonomy and term, if term is available. The template is
144  * prepended with 'taxonomy-' and followed by both the taxonomy string and
145  * the taxonomy string followed by a dash and then followed by the term.
146  *
147  * The taxonomy and term template is checked and used first, if it exists.
148  * Second, just the taxonomy template is checked, and then finally, taxonomy.php
149  * template is used. If none of the files exist, then it will fall back on to
150  * index.php.
151  *
152  * @since 2.5.0
153  * @uses apply_filters() Calls 'taxonomy_template' filter on found path.
154  *
155  * @return string
156  */
157 function get_taxonomy_template() {
158         $term = get_queried_object();
159         $taxonomy = $term->taxonomy;
160
161         $templates = array();
162
163         $templates[] = "taxonomy-$taxonomy-{$term->slug}.php";
164         $templates[] = "taxonomy-$taxonomy.php";
165         $templates[] = 'taxonomy.php';
166
167         return get_query_template( 'taxonomy', $templates );
168 }
169
170 /**
171  * Retrieve path of date template in current or parent template.
172  *
173  * @since 1.5.0
174  *
175  * @return string
176  */
177 function get_date_template() {
178         return get_query_template('date');
179 }
180
181 /**
182  * Retrieve path of home template in current or parent template.
183  *
184  * This is the template used for the page containing the blog posts
185  *
186  * Attempts to locate 'home.php' first before falling back to 'index.php'.
187  *
188  * @since 1.5.0
189  * @uses apply_filters() Calls 'home_template' on file path of home template.
190  *
191  * @return string
192  */
193 function get_home_template() {
194         $templates = array( 'home.php', 'index.php' );
195
196         return get_query_template( 'home', $templates );
197 }
198
199 /**
200  * Retrieve path of front-page template in current or parent template.
201  *
202  * Looks for 'front-page.php'.
203  *
204  * @since 3.0.0
205  * @uses apply_filters() Calls 'front_page_template' on file path of template.
206  *
207  * @return string
208  */
209 function get_front_page_template() {
210         $templates = array('front-page.php');
211
212         return get_query_template( 'front_page', $templates );
213 }
214
215 /**
216  * Retrieve path of page template in current or parent template.
217  *
218  * Will first look for the specifically assigned page template
219  * The will search for 'page-{slug}.php' followed by 'page-id.php'
220  * and finally 'page.php'
221  *
222  * @since 1.5.0
223  *
224  * @return string
225  */
226 function get_page_template() {
227         $id = get_queried_object_id();
228         $template = get_page_template_slug();
229         $pagename = get_query_var('pagename');
230
231         if ( ! $pagename && $id ) {
232                 // If a static page is set as the front page, $pagename will not be set. Retrieve it from the queried object
233                 $post = get_queried_object();
234                 $pagename = $post->post_name;
235         }
236
237         $templates = array();
238         if ( $template && 0 === validate_file( $template ) )
239                 $templates[] = $template;
240         if ( $pagename )
241                 $templates[] = "page-$pagename.php";
242         if ( $id )
243                 $templates[] = "page-$id.php";
244         $templates[] = 'page.php';
245
246         return get_query_template( 'page', $templates );
247 }
248
249 /**
250  * Retrieve path of paged template in current or parent template.
251  *
252  * @since 1.5.0
253  *
254  * @return string
255  */
256 function get_paged_template() {
257         return get_query_template('paged');
258 }
259
260 /**
261  * Retrieve path of search template in current or parent template.
262  *
263  * @since 1.5.0
264  *
265  * @return string
266  */
267 function get_search_template() {
268         return get_query_template('search');
269 }
270
271 /**
272  * Retrieve path of single template in current or parent template.
273  *
274  * @since 1.5.0
275  *
276  * @return string
277  */
278 function get_single_template() {
279         $object = get_queried_object();
280
281         $templates = array();
282
283         $templates[] = "single-{$object->post_type}.php";
284         $templates[] = "single.php";
285
286         return get_query_template( 'single', $templates );
287 }
288
289 /**
290  * Retrieve path of attachment template in current or parent template.
291  *
292  * The attachment path first checks if the first part of the mime type exists.
293  * The second check is for the second part of the mime type. The last check is
294  * for both types separated by an underscore. If neither are found then the file
295  * 'attachment.php' is checked and returned.
296  *
297  * Some examples for the 'text/plain' mime type are 'text.php', 'plain.php', and
298  * finally 'text_plain.php'.
299  *
300  * @since 2.0.0
301  *
302  * @return string
303  */
304 function get_attachment_template() {
305         global $posts;
306         $type = explode('/', $posts[0]->post_mime_type);
307         if ( $template = get_query_template($type[0]) )
308                 return $template;
309         elseif ( $template = get_query_template($type[1]) )
310                 return $template;
311         elseif ( $template = get_query_template("$type[0]_$type[1]") )
312                 return $template;
313         else
314                 return get_query_template('attachment');
315 }
316
317 /**
318  * Retrieve path of comment popup template in current or parent template.
319  *
320  * Checks for comment popup template in current template, if it exists or in the
321  * parent template.
322  *
323  * @since 1.5.0
324  * @uses apply_filters() Calls 'comments_popup_template' filter on path.
325  *
326  * @return string
327  */
328 function get_comments_popup_template() {
329         $template = get_query_template( 'comments_popup', array( 'comments-popup.php' ) );
330
331         // Backward compat code will be removed in a future release
332         if ('' == $template)
333                 $template = ABSPATH . WPINC . '/theme-compat/comments-popup.php';
334
335         return $template;
336 }
337
338 /**
339  * Retrieve the name of the highest priority template file that exists.
340  *
341  * Searches in the STYLESHEETPATH before TEMPLATEPATH so that themes which
342  * inherit from a parent theme can just overload one file.
343  *
344  * @since 2.7.0
345  *
346  * @param string|array $template_names Template file(s) to search for, in order.
347  * @param bool $load If true the template file will be loaded if it is found.
348  * @param bool $require_once Whether to require_once or require. Default true. Has no effect if $load is false.
349  * @return string The template filename if one is located.
350  */
351 function locate_template($template_names, $load = false, $require_once = true ) {
352         $located = '';
353         foreach ( (array) $template_names as $template_name ) {
354                 if ( !$template_name )
355                         continue;
356                 if ( file_exists(STYLESHEETPATH . '/' . $template_name)) {
357                         $located = STYLESHEETPATH . '/' . $template_name;
358                         break;
359                 } else if ( file_exists(TEMPLATEPATH . '/' . $template_name) ) {
360                         $located = TEMPLATEPATH . '/' . $template_name;
361                         break;
362                 }
363         }
364
365         if ( $load && '' != $located )
366                 load_template( $located, $require_once );
367
368         return $located;
369 }
370
371 /**
372  * Require the template file with WordPress environment.
373  *
374  * The globals are set up for the template file to ensure that the WordPress
375  * environment is available from within the function. The query variables are
376  * also available.
377  *
378  * @since 1.5.0
379  *
380  * @param string $_template_file Path to template file.
381  * @param bool $require_once Whether to require_once or require. Default true.
382  */
383 function load_template( $_template_file, $require_once = true ) {
384         global $posts, $post, $wp_did_header, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID;
385
386         if ( is_array( $wp_query->query_vars ) )
387                 extract( $wp_query->query_vars, EXTR_SKIP );
388
389         if ( $require_once )
390                 require_once( $_template_file );
391         else
392                 require( $_template_file );
393 }
394