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