X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/fa11948979fd6a4ea5705dc613b239699a459db3..f5fcdc7994bb67cce809bc4777944ae8b7fad4a4:/wp-includes/general-template.php
diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php
index 90e19d4b..f9a529f0 100644
--- a/wp-includes/general-template.php
+++ b/wp-includes/general-template.php
@@ -15,13 +15,23 @@
* For the parameter, if the file is called "header-special.php" then specify
* "special".
*
- * @uses locate_template()
* @since 1.5.0
- * @uses do_action() Calls 'get_header' action.
*
* @param string $name The name of the specialised header.
*/
function get_header( $name = null ) {
+ /**
+ * Fires before the header template file is loaded.
+ *
+ * The hook allows a specific header template file to be used in place of the
+ * default header template file. If your file is called header-new.php,
+ * you would specify the filename in the hook as get_header( 'new' ).
+ *
+ * @since 2.1.0
+ * @since 2.8.0 $name parameter added.
+ *
+ * @param string $name Name of the specific header file to use.
+ */
do_action( 'get_header', $name );
$templates = array();
@@ -45,13 +55,23 @@ function get_header( $name = null ) {
* For the parameter, if the file is called "footer-special.php" then specify
* "special".
*
- * @uses locate_template()
* @since 1.5.0
- * @uses do_action() Calls 'get_footer' action.
*
* @param string $name The name of the specialised footer.
*/
function get_footer( $name = null ) {
+ /**
+ * Fires before the footer template file is loaded.
+ *
+ * The hook allows a specific footer template file to be used in place of the
+ * default footer template file. If your file is called footer-new.php,
+ * you would specify the filename in the hook as get_footer( 'new' ).
+ *
+ * @since 2.1.0
+ * @since 2.8.0 $name parameter added.
+ *
+ * @param string $name Name of the specific footer file to use.
+ */
do_action( 'get_footer', $name );
$templates = array();
@@ -75,13 +95,23 @@ function get_footer( $name = null ) {
* For the parameter, if the file is called "sidebar-special.php" then specify
* "special".
*
- * @uses locate_template()
* @since 1.5.0
- * @uses do_action() Calls 'get_sidebar' action.
*
* @param string $name The name of the specialised sidebar.
*/
function get_sidebar( $name = null ) {
+ /**
+ * Fires before the sidebar template file is loaded.
+ *
+ * The hook allows a specific sidebar template file to be used in place of the
+ * default sidebar template file. If your file is called sidebar-new.php,
+ * you would specify the filename in the hook as get_sidebar( 'new' ).
+ *
+ * @since 2.2.0
+ * @since 2.8.0 $name parameter added.
+ *
+ * @param string $name Name of the specific sidebar file to use.
+ */
do_action( 'get_sidebar', $name );
$templates = array();
@@ -112,14 +142,23 @@ function get_sidebar( $name = null ) {
* For the $name parameter, if the file is called "{slug}-special.php" then specify
* "special".
*
- * @uses locate_template()
* @since 3.0.0
- * @uses do_action() Calls 'get_template_part_{$slug}' action.
*
* @param string $slug The slug name for the generic template.
* @param string $name The name of the specialised template.
*/
function get_template_part( $slug, $name = null ) {
+ /**
+ * Fires before the specified template part file is loaded.
+ *
+ * The dynamic portion of the hook name, `$slug`, refers to the slug name
+ * for the generic template part.
+ *
+ * @since 3.0.0
+ *
+ * @param string $slug The slug name for the generic template.
+ * @param string $name The name of the specialized template.
+ */
do_action( "get_template_part_{$slug}", $slug, $name );
$templates = array();
@@ -150,16 +189,31 @@ function get_template_part( $slug, $name = null ) {
* search. To give a few examples of what it can be used for.
*
* @since 2.7.0
- * @uses apply_filters() Calls 'search_form_format' filter to determine which type to use for the search field.
- * If set to 'html5', it changes to search input type and adds placeholder text.
*
* @param boolean $echo Default to echo and not return the form.
* @return string|null String when retrieving, null when displaying or if searchform.php exists.
*/
function get_search_form( $echo = true ) {
+ /**
+ * Fires before the search form is retrieved, at the start of get_search_form().
+ *
+ * @since 2.7.0 as 'get_search_form' action.
+ * @since 3.6.0
+ *
+ * @link https://core.trac.wordpress.org/ticket/19321
+ */
do_action( 'pre_get_search_form' );
$format = current_theme_supports( 'html5', 'search-form' ) ? 'html5' : 'xhtml';
+
+ /**
+ * Filter the HTML format of the search form.
+ *
+ * @since 3.6.0
+ *
+ * @param string $format The type of markup to use in the search form.
+ * Accepts 'html5', 'xhtml'.
+ */
$format = apply_filters( 'search_form_format', $format );
$search_form_template = locate_template( 'searchform.php' );
@@ -187,7 +241,15 @@ function get_search_form( $echo = true ) {
}
}
+ /**
+ * Filter the HTML output of the search form.
+ *
+ * @since 2.7.0
+ *
+ * @param string $form The search form HTML output.
+ */
$result = apply_filters( 'get_search_form', $form );
+
if ( null === $result )
$result = $form;
@@ -204,7 +266,6 @@ function get_search_form( $echo = true ) {
* or log out depending on whether they are currently logged in.
*
* @since 1.5.0
- * @uses apply_filters() Calls 'loginout' hook on HTML link content.
*
* @param string $redirect Optional path to redirect to on login/logout.
* @param boolean $echo Default to echo and not return the link.
@@ -216,10 +277,19 @@ function wp_loginout($redirect = '', $echo = true) {
else
$link = '' . __('Log out') . '';
- if ( $echo )
- echo apply_filters('loginout', $link);
- else
- return apply_filters('loginout', $link);
+ if ( $echo ) {
+ /**
+ * Filter the HTML output for the Log In/Log Out link.
+ *
+ * @since 1.5.0
+ *
+ * @param string $link The HTML link content.
+ */
+ echo apply_filters( 'loginout', $link );
+ } else {
+ /** This filter is documented in wp-includes/general-template.php */
+ return apply_filters( 'loginout', $link );
+ }
}
/**
@@ -228,9 +298,6 @@ function wp_loginout($redirect = '', $echo = true) {
* Returns the URL that allows the user to log out of the site.
*
* @since 2.7.0
- * @uses wp_nonce_url() To protect against CSRF.
- * @uses site_url() To generate the log out URL.
- * @uses apply_filters() calls 'logout_url' hook on final logout URL.
*
* @param string $redirect Path to redirect to on logout.
* @return string A log out URL.
@@ -244,7 +311,15 @@ function wp_logout_url($redirect = '') {
$logout_url = add_query_arg($args, site_url('wp-login.php', 'login'));
$logout_url = wp_nonce_url( $logout_url, 'log-out' );
- return apply_filters('logout_url', $logout_url, $redirect);
+ /**
+ * Filter the logout URL.
+ *
+ * @since 2.8.0
+ *
+ * @param string $logout_url The Log Out URL.
+ * @param string $redirect Path to redirect to on logout.
+ */
+ return apply_filters( 'logout_url', $logout_url, $redirect );
}
/**
@@ -253,8 +328,6 @@ function wp_logout_url($redirect = '') {
* Returns the URL that allows the user to log in to the site.
*
* @since 2.7.0
- * @uses site_url() To generate the log in URL.
- * @uses apply_filters() calls 'login_url' hook on final login URL.
*
* @param string $redirect Path to redirect to on login.
* @param bool $force_reauth Whether to force reauthorization, even if a cookie is present. Default is false.
@@ -269,7 +342,17 @@ function wp_login_url($redirect = '', $force_reauth = false) {
if ( $force_reauth )
$login_url = add_query_arg('reauth', '1', $login_url);
- return apply_filters('login_url', $login_url, $redirect);
+ /**
+ * Filter the login URL.
+ *
+ * @since 2.8.0
+ * @since 4.2.0 The `$force_reauth` parameter was added.
+ *
+ * @param string $login_url The login URL.
+ * @param string $redirect The path to redirect to on login, if supplied.
+ * @param bool $force_reauth Whether to force reauthorization, even if a cookie is present.
+ */
+ return apply_filters( 'login_url', $login_url, $redirect, $force_reauth );
}
/**
@@ -278,12 +361,17 @@ function wp_login_url($redirect = '', $force_reauth = false) {
* Returns the URL that allows the user to register on the site.
*
* @since 3.6.0
- * @uses site_url() To generate the registration URL.
- * @uses apply_filters() calls 'register_url' hook on final URL.
*
- * @return string
+ * @return string User registration URL.
*/
function wp_registration_url() {
+ /**
+ * Filter the user registration URL.
+ *
+ * @since 3.6.0
+ *
+ * @param string $register The user registration URL.
+ */
return apply_filters( 'register_url', site_url( 'wp-login.php?action=register', 'login' ) );
}
@@ -292,6 +380,7 @@ function wp_registration_url() {
* the HTML immediately. Pass array('echo'=>false) to return the string instead.
*
* @since 3.0.0
+ *
* @param array $args Configuration options to modify the form output.
* @return string|null String when retrieving, null when displaying.
*/
@@ -312,11 +401,58 @@ function wp_login_form( $args = array() ) {
'value_username' => '',
'value_remember' => false, // Set this to true to default the "Remember me" checkbox to checked
);
+
+ /**
+ * Filter the default login form output arguments.
+ *
+ * @since 3.0.0
+ *
+ * @see wp_login_form()
+ *
+ * @param array $defaults An array of default login form arguments.
+ */
$args = wp_parse_args( $args, apply_filters( 'login_form_defaults', $defaults ) );
+ /**
+ * Filter content to display at the top of the login form.
+ *
+ * The filter evaluates just following the opening form tag element.
+ *
+ * @since 3.0.0
+ *
+ * @param string $content Content to display. Default empty.
+ * @param array $args Array of login form arguments.
+ */
+ $login_form_top = apply_filters( 'login_form_top', '', $args );
+
+ /**
+ * Filter content to display in the middle of the login form.
+ *
+ * The filter evaluates just following the location where the 'login-password'
+ * field is displayed.
+ *
+ * @since 3.0.0
+ *
+ * @param string $content Content to display. Default empty.
+ * @param array $args Array of login form arguments.
+ */
+ $login_form_middle = apply_filters( 'login_form_middle', '', $args );
+
+ /**
+ * Filter content to display at the bottom of the login form.
+ *
+ * The filter evaluates just preceding the closing form tag element.
+ *
+ * @since 3.0.0
+ *
+ * @param string $content Content to display. Default empty.
+ * @param array $args Array of login form arguments.
+ */
+ $login_form_bottom = apply_filters( 'login_form_bottom', '', $args );
+
$form = '
';
if ( $args['echo'] )
@@ -346,8 +482,6 @@ function wp_login_form( $args = array() ) {
* Returns the URL that allows the user to retrieve the lost password
*
* @since 2.8.0
- * @uses site_url() To generate the lost password URL
- * @uses apply_filters() calls 'lostpassword_url' hook on the lostpassword url
*
* @param string $redirect Path to redirect to on login.
* @return string Lost password URL.
@@ -359,6 +493,15 @@ function wp_lostpassword_url( $redirect = '' ) {
}
$lostpassword_url = add_query_arg( $args, network_site_url('wp-login.php', 'login') );
+
+ /**
+ * Filter the Lost Password URL.
+ *
+ * @since 2.8.0
+ *
+ * @param string $lostpassword_url The lost password page URL.
+ * @param string $redirect The path to redirect to on login.
+ */
return apply_filters( 'lostpassword_url', $lostpassword_url, $redirect );
}
@@ -369,10 +512,9 @@ function wp_lostpassword_url( $redirect = '' ) {
* not logged in and registration is enabled or to the dashboard if logged in.
*
* @since 1.5.0
- * @uses apply_filters() Calls 'register' hook on register / admin link content.
*
- * @param string $before Text to output before the link (defaults to
).
- * @param string $after Text to output after the link (defaults to
).
+ * @param string $before Text to output before the link. Default `
`.
+ * @param string $after Text to output after the link. Default `
`.
* @param boolean $echo Default to echo and not return the link.
* @return string|null String when retrieving, null when displaying.
*/
@@ -387,10 +529,23 @@ function wp_register( $before = '
', $after = '
', $echo = true ) {
$link = $before . '' . __('Site Admin') . '' . $after;
}
- if ( $echo )
- echo apply_filters('register', $link);
- else
- return apply_filters('register', $link);
+ /**
+ * Filter the HTML link to the Registration or Admin page.
+ *
+ * Users are sent to the admin page if logged-in, or the registration page
+ * if enabled and logged-out.
+ *
+ * @since 1.5.0
+ *
+ * @param string $link The HTML code for the link to the Registration or Admin page.
+ */
+ $link = apply_filters( 'register', $link );
+
+ if ( $echo ) {
+ echo $link;
+ } else {
+ return $link;
+ }
}
/**
@@ -400,11 +555,16 @@ function wp_register( $before = '
', $after = '
', $echo = true ) {
* but one purpose might have been to allow for theme switching.
*
* @since 1.5.0
- * @link http://trac.wordpress.org/ticket/1458 Explanation of 'wp_meta' action.
- * @uses do_action() Calls 'wp_meta' hook.
+ *
+ * @link https://core.trac.wordpress.org/ticket/1458 Explanation of 'wp_meta' action.
*/
function wp_meta() {
- do_action('wp_meta');
+ /**
+ * Fires before displaying echoed content in the sidebar.
+ *
+ * @since 1.5.0
+ */
+ do_action( 'wp_meta' );
}
/**
@@ -423,15 +583,15 @@ function bloginfo( $show='' ) {
* Retrieve information about the blog.
*
* Some show parameter values are deprecated and will be removed in future
- * versions. These options will trigger the _deprecated_argument() function.
- * The deprecated blog info options are listed in the function contents.
+ * versions. These options will trigger the {@see _deprecated_argument()}
+ * function. The deprecated blog info options are listed in the function
+ * contents.
*
* The possible values for the 'show' parameter are listed below.
- *
- *
url - Blog URI to homepage.
- *
wpurl - Blog URI path to WordPress.
- *
description - Secondary title
- *
+ *
+ * 1. url - Blog URI to homepage.
+ * 2. wpurl - Blog URI path to WordPress.
+ * 3. description - Secondary title
*
* The feed URL options can be retrieved from 'rdf_url' (RSS 0.91),
* 'rss_url' (RSS 1.0), 'rss2_url' (RSS 2.0), or 'atom_url' (Atom feed). The
@@ -449,7 +609,13 @@ function get_bloginfo( $show = '', $filter = 'raw' ) {
switch( $show ) {
case 'home' : // DEPRECATED
case 'siteurl' : // DEPRECATED
- _deprecated_argument( __FUNCTION__, '2.2', sprintf( __('The %s option is deprecated for the family of bloginfo() functions.' ), $show ) . ' ' . sprintf( __( 'Use the %s option instead.' ), 'url' ) );
+ _deprecated_argument( __FUNCTION__, '2.2', sprintf(
+ /* translators: 1: 'siteurl'/'home' argument, 2: bloginfo() function name, 3: 'url' argument */
+ __( 'The %1$s option is deprecated for the family of %2$s functions. Use the %3$s option instead.' ),
+ '' . $show . '',
+ 'bloginfo()',
+ 'url'
+ ) );
case 'url' :
$output = home_url();
break;
@@ -509,7 +675,13 @@ function get_bloginfo( $show = '', $filter = 'raw' ) {
$output = str_replace('_', '-', $output);
break;
case 'text_direction':
- //_deprecated_argument( __FUNCTION__, '2.2', sprintf( __('The %s option is deprecated for the family of bloginfo() functions.' ), $show ) . ' ' . sprintf( __( 'Use the %s function instead.' ), 'is_rtl()' ) );
+ _deprecated_argument( __FUNCTION__, '2.2', sprintf(
+ /* translators: 1: 'text_direction' argument, 2: bloginfo() function name, 3: is_rtl() function name */
+ __( 'The %1$s option is deprecated for the family of %2$s functions. Use the %3$s function instead.' ),
+ '' . $show . '',
+ 'bloginfo()',
+ 'is_rtl()'
+ ) );
if ( function_exists( 'is_rtl' ) ) {
$output = is_rtl() ? 'rtl' : 'ltr';
} else {
@@ -529,15 +701,54 @@ function get_bloginfo( $show = '', $filter = 'raw' ) {
$url = false;
if ( 'display' == $filter ) {
- if ( $url )
- $output = apply_filters('bloginfo_url', $output, $show);
- else
- $output = apply_filters('bloginfo', $output, $show);
+ if ( $url ) {
+ /**
+ * Filter the URL returned by get_bloginfo().
+ *
+ * @since 2.0.5
+ *
+ * @param mixed $output The URL returned by bloginfo().
+ * @param mixed $show Type of information requested.
+ */
+ $output = apply_filters( 'bloginfo_url', $output, $show );
+ } else {
+ /**
+ * Filter the site information returned by get_bloginfo().
+ *
+ * @since 0.71
+ *
+ * @param mixed $output The requested non-URL site information.
+ * @param mixed $show Type of information requested.
+ */
+ $output = apply_filters( 'bloginfo', $output, $show );
+ }
}
return $output;
}
+/**
+ * Display title tag with contents.
+ *
+ * @ignore
+ * @since 4.1.0
+ * @access private
+ *
+ * @see wp_title()
+ */
+function _wp_render_title_tag() {
+ if ( ! current_theme_supports( 'title-tag' ) ) {
+ return;
+ }
+
+ // This can only work internally on wp_head.
+ if ( ! did_action( 'wp_head' ) && ! doing_action( 'wp_head' ) ) {
+ return;
+ }
+
+ echo '' . wp_title( '|', false, 'right' ) . "\n";
+}
+
/**
* Display or retrieve page title for all areas of blog.
*
@@ -561,7 +772,7 @@ function get_bloginfo( $show = '', $filter = 'raw' ) {
* @return string|null String on retrieve, null when displaying.
*/
function wp_title($sep = '»', $display = true, $seplocation = '') {
- global $wpdb, $wp_locale;
+ global $wp_locale, $page, $paged;
$m = get_query_var('m');
$year = get_query_var('year');
@@ -602,7 +813,7 @@ function wp_title($sep = '»', $display = true, $seplocation = '') {
}
// If there's an author
- if ( is_author() ) {
+ if ( is_author() && ! is_post_type_archive() ) {
$author = get_queried_object();
if ( $author )
$title = $author->display_name;
@@ -644,17 +855,46 @@ function wp_title($sep = '»', $display = true, $seplocation = '') {
if ( !empty($title) )
$prefix = " $sep ";
+ /**
+ * Filter the parts of the page title.
+ *
+ * @since 4.0.0
+ *
+ * @param array $title_array Parts of the page title.
+ */
+ $title_array = apply_filters( 'wp_title_parts', explode( $t_sep, $title ) );
+
// Determines position of the separator and direction of the breadcrumb
if ( 'right' == $seplocation ) { // sep on right, so reverse the order
- $title_array = explode( $t_sep, $title );
$title_array = array_reverse( $title_array );
$title = implode( " $sep ", $title_array ) . $prefix;
} else {
- $title_array = explode( $t_sep, $title );
$title = $prefix . implode( " $sep ", $title_array );
}
- $title = apply_filters('wp_title', $title, $sep, $seplocation);
+ if ( current_theme_supports( 'title-tag' ) && ! is_feed() ) {
+ $title .= get_bloginfo( 'name', 'display' );
+
+ $site_description = get_bloginfo( 'description', 'display' );
+ if ( $site_description && ( is_home() || is_front_page() ) ) {
+ $title .= " $sep $site_description";
+ }
+
+ if ( ( $paged >= 2 || $page >= 2 ) && ! is_404() ) {
+ $title .= " $sep " . sprintf( __( 'Page %s' ), max( $paged, $page ) );
+ }
+ }
+
+ /**
+ * Filter the text of the page title.
+ *
+ * @since 2.0.0
+ *
+ * @param string $title Page title.
+ * @param string $sep Title separator.
+ * @param string $seplocation Location of the separator (left or right).
+ */
+ $title = apply_filters( 'wp_title', $title, $sep, $seplocation );
// Send it out
if ( $display )
@@ -686,7 +926,15 @@ function single_post_title($prefix = '', $display = true) {
if ( !isset($_post->post_title) )
return;
- $title = apply_filters('single_post_title', $_post->post_title, $_post);
+ /**
+ * Filter the page title for a single post.
+ *
+ * @since 0.71
+ *
+ * @param string $_post_title The single post page title.
+ * @param object $_post The current queried object as returned by get_queried_object().
+ */
+ $title = apply_filters( 'single_post_title', $_post->post_title, $_post );
if ( $display )
echo $prefix . $title;
else
@@ -714,7 +962,16 @@ function post_type_archive_title( $prefix = '', $display = true ) {
$post_type = reset( $post_type );
$post_type_obj = get_post_type_object( $post_type );
- $title = apply_filters('post_type_archive_title', $post_type_obj->labels->name );
+
+ /**
+ * Filter the post type archive title.
+ *
+ * @since 3.1.0
+ *
+ * @param string $post_type_name Post type 'name' label.
+ * @param string $post_type Post type.
+ */
+ $title = apply_filters( 'post_type_archive_title', $post_type_obj->labels->name, $post_type );
if ( $display )
echo $prefix . $title;
@@ -787,14 +1044,36 @@ function single_term_title( $prefix = '', $display = true ) {
if ( !$term )
return;
- if ( is_category() )
+ if ( is_category() ) {
+ /**
+ * Filter the category archive page title.
+ *
+ * @since 2.0.10
+ *
+ * @param string $term_name Category name for archive being displayed.
+ */
$term_name = apply_filters( 'single_cat_title', $term->name );
- elseif ( is_tag() )
+ } elseif ( is_tag() ) {
+ /**
+ * Filter the tag archive page title.
+ *
+ * @since 2.3.0
+ *
+ * @param string $term_name Tag name for archive being displayed.
+ */
$term_name = apply_filters( 'single_tag_title', $term->name );
- elseif ( is_tax() )
+ } elseif ( is_tax() ) {
+ /**
+ * Filter the custom taxonomy archive page title.
+ *
+ * @since 3.1.0
+ *
+ * @param string $term_name Term name for archive being displayed.
+ */
$term_name = apply_filters( 'single_term_title', $term->name );
- else
+ } else {
return;
+ }
if ( empty( $term_name ) )
return;
@@ -848,6 +1127,121 @@ function single_month_title($prefix = '', $display = true ) {
echo $result;
}
+/**
+ * Display the archive title based on the queried object.
+ *
+ * @since 4.1.0
+ *
+ * @see get_the_archive_title()
+ *
+ * @param string $before Optional. Content to prepend to the title. Default empty.
+ * @param string $after Optional. Content to append to the title. Default empty.
+ */
+function the_archive_title( $before = '', $after = '' ) {
+ $title = get_the_archive_title();
+
+ if ( ! empty( $title ) ) {
+ echo $before . $title . $after;
+ }
+}
+
+/**
+ * Retrieve the archive title based on the queried object.
+ *
+ * @since 4.1.0
+ *
+ * @return string Archive title.
+ */
+function get_the_archive_title() {
+ if ( is_category() ) {
+ $title = sprintf( __( 'Category: %s' ), single_cat_title( '', false ) );
+ } elseif ( is_tag() ) {
+ $title = sprintf( __( 'Tag: %s' ), single_tag_title( '', false ) );
+ } elseif ( is_author() ) {
+ $title = sprintf( __( 'Author: %s' ), '' . get_the_author() . '' );
+ } elseif ( is_year() ) {
+ $title = sprintf( __( 'Year: %s' ), get_the_date( _x( 'Y', 'yearly archives date format' ) ) );
+ } elseif ( is_month() ) {
+ $title = sprintf( __( 'Month: %s' ), get_the_date( _x( 'F Y', 'monthly archives date format' ) ) );
+ } elseif ( is_day() ) {
+ $title = sprintf( __( 'Day: %s' ), get_the_date( _x( 'F j, Y', 'daily archives date format' ) ) );
+ } elseif ( is_tax( 'post_format' ) ) {
+ if ( is_tax( 'post_format', 'post-format-aside' ) ) {
+ $title = _x( 'Asides', 'post format archive title' );
+ } elseif ( is_tax( 'post_format', 'post-format-gallery' ) ) {
+ $title = _x( 'Galleries', 'post format archive title' );
+ } elseif ( is_tax( 'post_format', 'post-format-image' ) ) {
+ $title = _x( 'Images', 'post format archive title' );
+ } elseif ( is_tax( 'post_format', 'post-format-video' ) ) {
+ $title = _x( 'Videos', 'post format archive title' );
+ } elseif ( is_tax( 'post_format', 'post-format-quote' ) ) {
+ $title = _x( 'Quotes', 'post format archive title' );
+ } elseif ( is_tax( 'post_format', 'post-format-link' ) ) {
+ $title = _x( 'Links', 'post format archive title' );
+ } elseif ( is_tax( 'post_format', 'post-format-status' ) ) {
+ $title = _x( 'Statuses', 'post format archive title' );
+ } elseif ( is_tax( 'post_format', 'post-format-audio' ) ) {
+ $title = _x( 'Audio', 'post format archive title' );
+ } elseif ( is_tax( 'post_format', 'post-format-chat' ) ) {
+ $title = _x( 'Chats', 'post format archive title' );
+ }
+ } elseif ( is_post_type_archive() ) {
+ $title = sprintf( __( 'Archives: %s' ), post_type_archive_title( '', false ) );
+ } elseif ( is_tax() ) {
+ $tax = get_taxonomy( get_queried_object()->taxonomy );
+ /* translators: 1: Taxonomy singular name, 2: Current taxonomy term */
+ $title = sprintf( __( '%1$s: %2$s' ), $tax->labels->singular_name, single_term_title( '', false ) );
+ } else {
+ $title = __( 'Archives' );
+ }
+
+ /**
+ * Filter the archive title.
+ *
+ * @since 4.1.0
+ *
+ * @param string $title Archive title to be displayed.
+ */
+ return apply_filters( 'get_the_archive_title', $title );
+}
+
+/**
+ * Display category, tag, or term description.
+ *
+ * @since 4.1.0
+ *
+ * @see get_the_archive_description()
+ *
+ * @param string $before Optional. Content to prepend to the description. Default empty.
+ * @param string $after Optional. Content to append to the description. Default empty.
+ */
+function the_archive_description( $before = '', $after = '' ) {
+ $description = get_the_archive_description();
+ if ( $description ) {
+ echo $before . $description . $after;
+ }
+}
+
+/**
+ * Retrieve category, tag, or term description.
+ *
+ * @since 4.1.0
+ *
+ * @return string Archive description.
+ */
+function get_the_archive_description() {
+ /**
+ * Filter the archive description.
+ *
+ * @since 4.1.0
+ *
+ * @see term_description()
+ *
+ * @param string $description Archive description to be displayed.
+ */
+ return apply_filters( 'get_the_archive_description', term_description() );
+}
+
/**
* Retrieve archive link content based on predefined or custom code.
*
@@ -856,7 +1250,7 @@ function single_month_title($prefix = '', $display = true ) {
* elements). Custom content is also supported using the before and after
* parameters.
*
- * The 'link' format uses the link HTML element with the archives
+ * The 'link' format uses the `` HTML element with the **archives**
* relationship. The before and after parameters are not used. The text
* parameter is used to describe the link.
*
@@ -874,6 +1268,8 @@ function single_month_title($prefix = '', $display = true ) {
*
* @since 1.0.0
*
+ * @todo Properly document optional arguments as such
+ *
* @param string $url URL to archive.
* @param string $text Archive text description.
* @param string $format Optional, default is 'html'. Can be 'link', 'option', 'html', or custom.
@@ -894,6 +1290,13 @@ function get_archives_link($url, $text, $format = 'html', $before = '', $after =
else // custom
$link_html = "\t$before$text$after\n";
+ /**
+ * Filter the archive link content.
+ *
+ * @since 2.6.0
+ *
+ * @param string $link_html The archive HTML link content.
+ */
$link_html = apply_filters( 'get_archives_link', $link_html );
return $link_html;
@@ -902,31 +1305,34 @@ function get_archives_link($url, $text, $format = 'html', $before = '', $after =
/**
* Display archive links based on type and format.
*
- * The 'type' argument offers a few choices and by default will display monthly
- * archive links. The other options for values are 'daily', 'weekly', 'monthly',
- * 'yearly', 'postbypost' or 'alpha'. Both 'postbypost' and 'alpha' display the
- * same archive link list, the difference between the two is that 'alpha'
- * will order by post title and 'postbypost' will order by post date.
- *
- * The date archives will logically display dates with links to the archive post
- * page. The 'postbypost' and 'alpha' values for 'type' argument will display
- * the post titles.
- *
- * The 'limit' argument will only display a limited amount of links, specified
- * by the 'limit' integer value. By default, there is no limit. The
- * 'show_post_count' argument will show how many posts are within the archive.
- * By default, the 'show_post_count' argument is set to false.
- *
- * For the 'format', 'before', and 'after' arguments, see {@link
- * get_archives_link()}. The values of these arguments have to do with that
- * function.
- *
* @since 1.2.0
*
- * @param string|array $args Optional. Override defaults.
+ * @see get_archives_link()
+ *
+ * @param string|array $args {
+ * Default archive links arguments. Optional.
+ *
+ * @type string $type Type of archive to retrieve. Accepts 'daily', 'weekly', 'monthly',
+ * 'yearly', 'postbypost', or 'alpha'. Both 'postbypost' and 'alpha'
+ * display the same archive link list as well as post titles instead
+ * of displaying dates. The difference between the two is that 'alpha'
+ * will order by post title and 'postbypost' will order by post date.
+ * Default 'monthly'.
+ * @type string|int $limit Number of links to limit the query to. Default empty (no limit).
+ * @type string $format Format each link should take using the $before and $after args.
+ * Accepts 'link' (`` tag), 'option' (`