<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[26906] trunk/src/wp-includes/template.php: Inline documentation improvements for get_*_template() functions in wp-includes/template.php.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="http://core.trac.wordpress.org/changeset/26906">26906</a></dd>
<dt>Author</dt> <dd>DrewAPicture</dd>
<dt>Date</dt> <dd>2014-01-05 17:54:07 +0000 (Sun, 05 Jan 2014)</dd>
</dl>
<h3>Log Message</h3>
<pre>Inline documentation improvements for get_*_template() functions in wp-includes/template.php.
* Adds `@see` references for `get_query_template()` or similar
* Adds complete `@return` descriptions
* Clarifies which dynamic hooks can be used to filter specific template types
Props UmeshSingla for the initial patches. Props SergeyBiryukov, DrewAPicture.
Fixes <a href="http://core.trac.wordpress.org/ticket/26742">#26742</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpincludestemplatephp">trunk/src/wp-includes/template.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpincludestemplatephp"></a>
<div class="modfile"><h4>Modified: trunk/src/wp-includes/template.php (26905 => 26906)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/src/wp-includes/template.php 2014-01-05 17:15:14 UTC (rev 26905)
+++ trunk/src/wp-includes/template.php 2014-01-05 17:54:07 UTC (rev 26906)
</span><span class="lines">@@ -18,7 +18,7 @@
</span><span class="cx"> *
</span><span class="cx"> * @param string $type Filename without extension.
</span><span class="cx"> * @param array $templates An optional list of template candidates
</span><del>- * @return string Full path to file.
</del><ins>+ * @return string Full path to template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_query_template( $type, $templates = array() ) {
</span><span class="cx"> $type = preg_replace( '|[^a-z0-9-]+|', '', $type );
</span><span class="lines">@@ -44,9 +44,13 @@
</span><span class="cx"> /**
</span><span class="cx"> * Retrieve path of index template in current or parent template.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the 'index_template' hook.
+ *
</ins><span class="cx"> * @since 3.0.0
</span><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to index template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_index_template() {
</span><span class="cx"> return get_query_template('index');
</span><span class="lines">@@ -55,9 +59,13 @@
</span><span class="cx"> /**
</span><span class="cx"> * Retrieve path of 404 template in current or parent template.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the '404_template' hook.
+ *
</ins><span class="cx"> * @since 1.5.0
</span><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to 404 template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_404_template() {
</span><span class="cx"> return get_query_template('404');
</span><span class="lines">@@ -66,9 +74,13 @@
</span><span class="cx"> /**
</span><span class="cx"> * Retrieve path of archive template in current or parent template.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the 'archive_template' hook.
+ *
</ins><span class="cx"> * @since 1.5.0
</span><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to archive template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_archive_template() {
</span><span class="cx"> $post_types = array_filter( (array) get_query_var( 'post_type' ) );
</span><span class="lines">@@ -87,9 +99,13 @@
</span><span class="cx"> /**
</span><span class="cx"> * Retrieve path of post type archive template in current or parent template.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the 'archive_template' hook.
+ *
</ins><span class="cx"> * @since 3.7.0
</span><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_archive_template()
+ *
+ * @return string Full path to archive template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_post_type_archive_template() {
</span><span class="cx"> $post_type = get_query_var( 'post_type' );
</span><span class="lines">@@ -106,9 +122,13 @@
</span><span class="cx"> /**
</span><span class="cx"> * Retrieve path of author template in current or parent template.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the 'author_template' hook.
+ *
</ins><span class="cx"> * @since 1.5.0
</span><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to author template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_author_template() {
</span><span class="cx"> $author = get_queried_object();
</span><span class="lines">@@ -131,10 +151,13 @@
</span><span class="cx"> * trying category ID, for example 'category-1.php', and will finally fall back to category.php
</span><span class="cx"> * template, if those files don't exist.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the 'category_template' hook.
+ *
</ins><span class="cx"> * @since 1.5.0
</span><del>- * @uses apply_filters() Calls 'category_template' on file path of category template.
</del><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to category template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_category_template() {
</span><span class="cx"> $category = get_queried_object();
</span><span class="lines">@@ -157,10 +180,13 @@
</span><span class="cx"> * trying tag ID, for example 'tag-1.php', and will finally fall back to tag.php
</span><span class="cx"> * template, if those files don't exist.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the 'tag_template' hook.
+ *
</ins><span class="cx"> * @since 2.3.0
</span><del>- * @uses apply_filters() Calls 'tag_template' on file path of tag template.
</del><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to tag template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_tag_template() {
</span><span class="cx"> $tag = get_queried_object();
</span><span class="lines">@@ -188,10 +214,13 @@
</span><span class="cx"> * template is used. If none of the files exist, then it will fall back on to
</span><span class="cx"> * index.php.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the 'taxonomy_template' hook.
+ *
</ins><span class="cx"> * @since 2.5.0
</span><del>- * @uses apply_filters() Calls 'taxonomy_template' filter on found path.
</del><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to taxonomy template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_taxonomy_template() {
</span><span class="cx"> $term = get_queried_object();
</span><span class="lines">@@ -211,9 +240,13 @@
</span><span class="cx"> /**
</span><span class="cx"> * Retrieve path of date template in current or parent template.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the 'date_template' hook.
+ *
</ins><span class="cx"> * @since 1.5.0
</span><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to date template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_date_template() {
</span><span class="cx"> return get_query_template('date');
</span><span class="lines">@@ -223,13 +256,15 @@
</span><span class="cx"> * Retrieve path of home template in current or parent template.
</span><span class="cx"> *
</span><span class="cx"> * This is the template used for the page containing the blog posts.
</span><del>- *
</del><span class="cx"> * Attempts to locate 'home.php' first before falling back to 'index.php'.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the 'home_template' hook.
+ *
</ins><span class="cx"> * @since 1.5.0
</span><del>- * @uses apply_filters() Calls 'home_template' on file path of home template.
</del><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to home template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_home_template() {
</span><span class="cx"> $templates = array( 'home.php', 'index.php' );
</span><span class="lines">@@ -240,12 +275,14 @@
</span><span class="cx"> /**
</span><span class="cx"> * Retrieve path of front-page template in current or parent template.
</span><span class="cx"> *
</span><del>- * Looks for 'front-page.php'.
</del><ins>+ * Looks for 'front-page.php'. The template path is filterable via the
+ * 'front_page_template' hook.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.0.0
</span><del>- * @uses apply_filters() Calls 'front_page_template' on file path of template.
</del><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to front page template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_front_page_template() {
</span><span class="cx"> $templates = array('front-page.php');
</span><span class="lines">@@ -260,9 +297,13 @@
</span><span class="cx"> * Then will search for 'page-{slug}.php', followed by 'page-{id}.php',
</span><span class="cx"> * and finally 'page.php'.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the 'page_template' hook.
+ *
</ins><span class="cx"> * @since 1.5.0
</span><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to page template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_page_template() {
</span><span class="cx"> $id = get_queried_object_id();
</span><span class="lines">@@ -291,9 +332,13 @@
</span><span class="cx"> /**
</span><span class="cx"> * Retrieve path of paged template in current or parent template.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the 'paged_template' hook.
+ *
</ins><span class="cx"> * @since 1.5.0
</span><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to paged template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_paged_template() {
</span><span class="cx"> return get_query_template('paged');
</span><span class="lines">@@ -302,9 +347,13 @@
</span><span class="cx"> /**
</span><span class="cx"> * Retrieve path of search template in current or parent template.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the 'search_template' hook.
+ *
</ins><span class="cx"> * @since 1.5.0
</span><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to search template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_search_template() {
</span><span class="cx"> return get_query_template('search');
</span><span class="lines">@@ -313,9 +362,13 @@
</span><span class="cx"> /**
</span><span class="cx"> * Retrieve path of single template in current or parent template.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the 'single_template' hook.
+ *
</ins><span class="cx"> * @since 1.5.0
</span><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to single template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_single_template() {
</span><span class="cx"> $object = get_queried_object();
</span><span class="lines">@@ -340,9 +393,13 @@
</span><span class="cx"> * Some examples for the 'text/plain' mime type are 'text.php', 'plain.php', and
</span><span class="cx"> * finally 'text_plain.php'.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the 'attachment_template' hook.
+ *
</ins><span class="cx"> * @since 2.0.0
</span><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to attachment template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_attachment_template() {
</span><span class="cx"> global $posts;
</span><span class="lines">@@ -371,10 +428,13 @@
</span><span class="cx"> * Checks for comment popup template in current template, if it exists or in the
</span><span class="cx"> * parent template.
</span><span class="cx"> *
</span><ins>+ * The template path is filterable via the 'comments_popup_template' hook.
+ *
</ins><span class="cx"> * @since 1.5.0
</span><del>- * @uses apply_filters() Calls 'comments_popup_template' filter on path.
</del><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @see get_query_template()
+ *
+ * @return string Full path to comments popup template file.
</ins><span class="cx"> */
</span><span class="cx"> function get_comments_popup_template() {
</span><span class="cx"> $template = get_query_template( 'comments_popup', array( 'comments-popup.php' ) );
</span></span></pre>
</div>
</div>
</body>
</html>