X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/41578db67d72562346e4dbb2a14889b23d522813..refs/tags/wordpress-4.4:/wp-includes/general-template.php diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php index f4d6f37d..f554e1fd 100644 --- a/wp-includes/general-template.php +++ b/wp-includes/general-template.php @@ -17,8 +17,6 @@ * * @since 1.5.0 * - * @uses locate_template() - * * @param string $name The name of the specialised header. */ function get_header( $name = null ) { @@ -59,8 +57,6 @@ function get_header( $name = null ) { * * @since 1.5.0 * - * @uses locate_template() - * * @param string $name The name of the specialised footer. */ function get_footer( $name = null ) { @@ -101,8 +97,6 @@ function get_footer( $name = null ) { * * @since 1.5.0 * - * @uses locate_template() - * * @param string $name The name of the specialised sidebar. */ function get_sidebar( $name = null ) { @@ -150,8 +144,6 @@ function get_sidebar( $name = null ) { * * @since 3.0.0 * - * @uses locate_template() - * * @param string $slug The slug name for the generic template. * @param string $name The name of the specialised template. */ @@ -159,7 +151,7 @@ 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 + * The dynamic portion of the hook name, `$slug`, refers to the slug name * for the generic template part. * * @since 3.0.0 @@ -198,8 +190,8 @@ function get_template_part( $slug, $name = null ) { * * @since 2.7.0 * - * @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. + * @param bool $echo Default to echo and not return the form. + * @return string|void String when $echo is false. */ function get_search_form( $echo = true ) { /** @@ -276,8 +268,8 @@ function get_search_form( $echo = true ) { * @since 1.5.0 * * @param string $redirect Optional path to redirect to on login/logout. - * @param boolean $echo Default to echo and not return the link. - * @return string|null String when retrieving, null when displaying. + * @param bool $echo Default to echo and not return the link. + * @return string|void String when retrieving. */ function wp_loginout($redirect = '', $echo = true) { if ( ! is_user_logged_in() ) @@ -307,9 +299,6 @@ function wp_loginout($redirect = '', $echo = true) { * * @since 2.7.0 * - * @uses wp_nonce_url() To protect against CSRF. - * @uses site_url() To generate the log out URL. - * * @param string $redirect Path to redirect to on logout. * @return string A log out URL. */ @@ -334,16 +323,12 @@ function wp_logout_url($redirect = '') { } /** - * Returns the Log In URL. - * * 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. - * - * @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. + * @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. * @return string A log in URL. */ function wp_login_url($redirect = '', $force_reauth = false) { @@ -359,22 +344,20 @@ function wp_login_url($redirect = '', $force_reauth = false) { * 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 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 ); + return apply_filters( 'login_url', $login_url, $redirect, $force_reauth ); } /** - * Returns the user registration URL. - * * Returns the URL that allows the user to register on the site. * * @since 3.6.0 * - * @uses site_url() To generate the registration URL. - * * @return string User registration URL. */ function wp_registration_url() { @@ -389,18 +372,41 @@ function wp_registration_url() { } /** - * Provides a simple login form for use anywhere within WordPress. By default, it echoes - * the HTML immediately. Pass array('echo'=>false) to return the string instead. + * Provides a simple login form for use anywhere within WordPress. + * + * The login format HTML is echoed by default. Pass a false value for `$echo` to return it instead. * * @since 3.0.0 * - * @param array $args Configuration options to modify the form output. - * @return string|null String when retrieving, null when displaying. + * @param array $args { + * Optional. Array of options to control the form output. Default empty array. + * + * @type bool $echo Whether to display the login form or return the form HTML code. + * Default true (echo). + * @type string $redirect URL to redirect to. Must be absolute, as in "https://example.com/mypage/". + * Default is to redirect back to the request URI. + * @type string $form_id ID attribute value for the form. Default 'loginform'. + * @type string $label_username Label for the username field. Default 'Username'. + * @type string $label_password Label for the password field. Default 'Password'. + * @type string $label_remember Label for the remember field. Default 'Remember Me'. + * @type string $label_log_in Label for the submit button. Default 'Log In'. + * @type string $id_username ID attribute value for the username field. Default 'user_login'. + * @type string $id_password ID attribute value for the password field. Default 'user_pass'. + * @type string $id_remember ID attribute value for the remember field. Default 'rememberme'. + * @type string $id_submit ID attribute value for the submit button. Default 'wp-submit'. + * @type bool $remember Whether to display the "rememberme" checkbox in the form. + * @type string $value_username Default value for the username field. Default empty. + * @type bool $value_remember Whether the "Remember Me" checkbox should be checked by default. + * Default false (unchecked). + * + * } + * @return string|void String when retrieving. */ function wp_login_form( $args = array() ) { $defaults = array( 'echo' => true, - 'redirect' => ( is_ssl() ? 'https://' : 'http://' ) . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'], // Default redirect is back to the current page + // Default 'redirect' value takes the user back to the request URI. + 'redirect' => ( is_ssl() ? 'https://' : 'http://' ) . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'], 'form_id' => 'loginform', 'label_username' => __( 'Username' ), 'label_password' => __( 'Password' ), @@ -412,7 +418,8 @@ function wp_login_form( $args = array() ) { 'id_submit' => 'wp-submit', 'remember' => true, 'value_username' => '', - 'value_remember' => false, // Set this to true to default the "Remember me" checkbox to checked + // Set 'value_remember' to true to default the "Remember me" checkbox to checked. + 'value_remember' => false, ); /** @@ -464,7 +471,7 @@ function wp_login_form( $args = array() ) { $login_form_bottom = apply_filters( 'login_form_bottom', '', $args ); $form = ' -
+ ' . $login_form_top . '

@@ -490,14 +497,10 @@ function wp_login_form( $args = array() ) { } /** - * Returns the Lost Password URL. - * * 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 - * * @param string $redirect Path to redirect to on login. * @return string Lost password URL. */ @@ -528,37 +531,39 @@ function wp_lostpassword_url( $redirect = '' ) { * * @since 1.5.0 * - * @param string $before Text to output before the link (defaults to

  • ). - * @param string $after Text to output after the link (defaults to
    • ). - * @param boolean $echo Default to echo and not return the link. - * @return string|null String when retrieving, null when displaying. + * @param string $before Text to output before the link. Default `
  • `. + * @param string $after Text to output after the link. Default `
    • `. + * @param bool $echo Default to echo and not return the link. + * @return string|void String when retrieving. */ function wp_register( $before = '
  • ', $after = '
    • ', $echo = true ) { - if ( ! is_user_logged_in() ) { if ( get_option('users_can_register') ) $link = $before . '' . __('Register') . '' . $after; else $link = ''; - } else { + } elseif ( current_user_can( 'read' ) ) { $link = $before . '' . __('Site Admin') . '' . $after; + } else { + $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 ) { - /** - * 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. - */ - echo apply_filters( 'register', $link ); + echo $link; } else { - /** This filter is documented in wp-includes/general-template.php */ - return apply_filters( 'register', $link ); + return $link; } } @@ -570,7 +575,7 @@ function wp_register( $before = '
  • ', $after = '
    • ', $echo = true ) { * * @since 1.5.0 * - * @link http://trac.wordpress.org/ticket/1458 Explanation of 'wp_meta' action. + * @link https://core.trac.wordpress.org/ticket/1458 Explanation of 'wp_meta' action. */ function wp_meta() { /** @@ -597,15 +602,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. - *
      - *
    1. url - Blog URI to homepage.
      2. - *
    2. wpurl - Blog URI path to WordPress.
      3. - *
    3. description - Secondary title
      4. - *
    + * + * 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 @@ -614,16 +619,23 @@ function bloginfo( $show='' ) { * * @since 0.71 * - * @param string $show Blog info to retrieve. + * @global string $wp_version + * + * @param string $show Blog info to retrieve. * @param string $filter How to filter what is retrieved. * @return string Mostly string values, might be empty. */ 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; @@ -683,7 +695,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 { @@ -729,6 +747,219 @@ function get_bloginfo( $show = '', $filter = 'raw' ) { return $output; } +/** + * Returns the Site Icon URL. + * + * @since 4.3.0 + * + * @param int $size Optional. Size of the site icon. Default 512 (pixels). + * @param string $url Optional. Fallback url if no site icon is found. Default empty. + * @param int $blog_id Optional. ID of the blog to get the site icon for. Default current blog. + * @return string Site Icon URL. + */ +function get_site_icon_url( $size = 512, $url = '', $blog_id = 0 ) { + if ( is_multisite() && (int) $blog_id !== get_current_blog_id() ) { + switch_to_blog( $blog_id ); + } + + $site_icon_id = get_option( 'site_icon' ); + + if ( $site_icon_id ) { + if ( $size >= 512 ) { + $size_data = 'full'; + } else { + $size_data = array( $size, $size ); + } + $url = wp_get_attachment_image_url( $site_icon_id, $size_data ); + } + + if ( is_multisite() && ms_is_switched() ) { + restore_current_blog(); + } + + /** + * Filter the site icon URL. + * + * @site 4.4.0 + * + * @param string $url Site icon URL. + * @param int $size Size of the site icon. + * @param int $blog_id ID of the blog to get the site icon for. + */ + return apply_filters( 'get_site_icon_url', $url, $size, $blog_id ); +} + +/** + * Displays the Site Icon URL. + * + * @since 4.3.0 + * + * @param int $size Optional. Size of the site icon. Default 512 (pixels). + * @param string $url Optional. Fallback url if no site icon is found. Default empty. + * @param int $blog_id Optional. ID of the blog to get the site icon for. Default current blog. + */ +function site_icon_url( $size = 512, $url = '', $blog_id = 0 ) { + echo esc_url( get_site_icon_url( $size, $url, $blog_id ) ); +} + +/** + * Whether the site has a Site Icon. + * + * @since 4.3.0 + * + * @param int $blog_id Optional. ID of the blog in question. Default current blog. + * @return bool Whether the site has a site icon or not. + */ +function has_site_icon( $blog_id = 0 ) { + return (bool) get_site_icon_url( 512, '', $blog_id ); +} + +/** + * Returns document title for the current page. + * + * @since 4.4.0 + * + * @global int $page Page number of a single post. + * @global int $paged Page number of a list of posts. + * + * @return string Tag with the document title. + */ +function wp_get_document_title() { + + /** + * Filter the document title before it is generated. + * + * Passing a non-empty value will short-circuit wp_get_document_title(), + * returning that value instead. + * + * @since 4.4.0 + * + * @param string $title The document title. Default empty string. + */ + $title = apply_filters( 'pre_get_document_title', '' ); + if ( ! empty( $title ) ) { + return $title; + } + + global $page, $paged; + + $title = array( + 'title' => '', + ); + + // If it's a 404 page, use a "Page not found" title. + if ( is_404() ) { + $title['title'] = __( 'Page not found' ); + + // If it's a search, use a dynamic search results title. + } elseif ( is_search() ) { + /* translators: %s: search phrase */ + $title['title'] = sprintf( __( 'Search Results for “%s”' ), get_search_query() ); + + // If on the home or front page, use the site title. + } elseif ( is_home() && is_front_page() ) { + $title['title'] = get_bloginfo( 'name', 'display' ); + + // If on a post type archive, use the post type archive title. + } elseif ( is_post_type_archive() ) { + $title['title'] = post_type_archive_title( '', false ); + + // If on a taxonomy archive, use the term title. + } elseif ( is_tax() ) { + $title['title'] = single_term_title( '', false ); + + /* + * If we're on the blog page and that page is not the homepage or a single + * page that is designated as the homepage, use the container page's title. + */ + } elseif ( ( is_home() && ! is_front_page() ) || ( ! is_home() && is_front_page() ) ) { + $title['title'] = single_post_title( '', false ); + + // If on a single post of any post type, use the post title. + } elseif ( is_singular() ) { + $title['title'] = single_post_title( '', false ); + + // If on a category or tag archive, use the term title. + } elseif ( is_category() || is_tag() ) { + $title['title'] = single_term_title( '', false ); + + // If on an author archive, use the author's display name. + } elseif ( is_author() && $author = get_queried_object() ) { + $title['title'] = $author->display_name; + + // If it's a date archive, use the date as the title. + } elseif ( is_year() ) { + $title['title'] = get_the_date( _x( 'Y', 'yearly archives date format' ) ); + + } elseif ( is_month() ) { + $title['title'] = get_the_date( _x( 'F Y', 'monthly archives date format' ) ); + + } elseif ( is_day() ) { + $title['title'] = get_the_date(); + } + + // Add a page number if necessary. + if ( ( $paged >= 2 || $page >= 2 ) && ! is_404() ) { + $title['page'] = sprintf( __( 'Page %s' ), max( $paged, $page ) ); + } + + // Append the description or site title to give context. + if ( is_home() && is_front_page() ) { + $title['tagline'] = get_bloginfo( 'description', 'display' ); + } else { + $title['site'] = get_bloginfo( 'name', 'display' ); + } + + /** + * Filter the separator for the document title. + * + * @since 4.4.0 + * + * @param string $sep Document title separator. Default '-'. + */ + $sep = apply_filters( 'document_title_separator', '-' ); + + /** + * Filter the parts of the document title. + * + * @since 4.4.0 + * + * @param array $title { + * The document title parts. + * + * @type string $title Title of the viewed page. + * @type string $page Optional. Page number if paginated. + * @type string $tagline Optional. Site description when on home page. + * @type string $site Optional. Site title when not on home page. + * } + */ + $title = apply_filters( 'document_title_parts', $title ); + + $title = implode( " $sep ", array_filter( $title ) ); + $title = wptexturize( $title ); + $title = convert_chars( $title ); + $title = esc_html( $title ); + $title = capital_P_dangit( $title ); + + return $title; +} + +/** + * Displays title tag with content. + * + * @ignore + * @since 4.1.0 + * @since 4.4.0 Improved title output replaced `wp_title()`. + * @access private + */ +function _wp_render_title_tag() { + if ( ! current_theme_supports( 'title-tag' ) ) { + return; + } + + echo '' . wp_get_document_title() . '' . "\n"; +} + /** * Display or retrieve page title for all areas of blog. * @@ -746,36 +977,41 @@ function get_bloginfo( $show = '', $filter = 'raw' ) { * * @since 1.0.0 * - * @param string $sep Optional, default is '»'. How to separate the various items within the page title. - * @param bool $display Optional, default is true. Whether to display or retrieve title. + * @global WP_Locale $wp_locale + * + * @param string $sep Optional, default is '»'. How to separate the various items + * within the page title. + * @param bool $display Optional, default is true. Whether to display or retrieve title. * @param string $seplocation Optional. Direction to display title, 'right'. * @return string|null String on retrieve, null when displaying. */ -function wp_title($sep = '»', $display = true, $seplocation = '') { - global $wpdb, $wp_locale; +function wp_title( $sep = '»', $display = true, $seplocation = '' ) { + global $wp_locale; - $m = get_query_var('m'); - $year = get_query_var('year'); - $monthnum = get_query_var('monthnum'); - $day = get_query_var('day'); - $search = get_query_var('s'); - $title = ''; + $m = get_query_var( 'm' ); + $year = get_query_var( 'year' ); + $monthnum = get_query_var( 'monthnum' ); + $day = get_query_var( 'day' ); + $search = get_query_var( 's' ); + $title = ''; $t_sep = '%WP_TITILE_SEP%'; // Temporary separator, for accurate flipping, if necessary // If there is a post - if ( is_single() || ( is_home() && !is_front_page() ) || ( is_page() && !is_front_page() ) ) { + if ( is_single() || ( is_home() && ! is_front_page() ) || ( is_page() && ! is_front_page() ) ) { $title = single_post_title( '', false ); } // If there's a post type archive if ( is_post_type_archive() ) { $post_type = get_query_var( 'post_type' ); - if ( is_array( $post_type ) ) + if ( is_array( $post_type ) ) { $post_type = reset( $post_type ); + } $post_type_object = get_post_type_object( $post_type ); - if ( ! $post_type_object->has_archive ) + if ( ! $post_type_object->has_archive ) { $title = post_type_archive_title( '', false ); + } } // If there's a category or tag @@ -787,61 +1023,73 @@ function wp_title($sep = '»', $display = true, $seplocation = '') { if ( is_tax() ) { $term = get_queried_object(); if ( $term ) { - $tax = get_taxonomy( $term->taxonomy ); + $tax = get_taxonomy( $term->taxonomy ); $title = single_term_title( $tax->labels->name . $t_sep, false ); } } // If there's an author - if ( is_author() ) { + if ( is_author() && ! is_post_type_archive() ) { $author = get_queried_object(); - if ( $author ) + if ( $author ) { $title = $author->display_name; + } } // Post type archives with has_archive should override terms. - if ( is_post_type_archive() && $post_type_object->has_archive ) + if ( is_post_type_archive() && $post_type_object->has_archive ) { $title = post_type_archive_title( '', false ); + } // If there's a month - if ( is_archive() && !empty($m) ) { - $my_year = substr($m, 0, 4); - $my_month = $wp_locale->get_month(substr($m, 4, 2)); - $my_day = intval(substr($m, 6, 2)); - $title = $my_year . ( $my_month ? $t_sep . $my_month : '' ) . ( $my_day ? $t_sep . $my_day : '' ); + if ( is_archive() && ! empty( $m ) ) { + $my_year = substr( $m, 0, 4 ); + $my_month = $wp_locale->get_month( substr( $m, 4, 2 ) ); + $my_day = intval( substr( $m, 6, 2 ) ); + $title = $my_year . ( $my_month ? $t_sep . $my_month : '' ) . ( $my_day ? $t_sep . $my_day : '' ); } // If there's a year - if ( is_archive() && !empty($year) ) { + if ( is_archive() && ! empty( $year ) ) { $title = $year; - if ( !empty($monthnum) ) - $title .= $t_sep . $wp_locale->get_month($monthnum); - if ( !empty($day) ) - $title .= $t_sep . zeroise($day, 2); + if ( ! empty( $monthnum ) ) { + $title .= $t_sep . $wp_locale->get_month( $monthnum ); + } + if ( ! empty( $day ) ) { + $title .= $t_sep . zeroise( $day, 2 ); + } } // If it's a search if ( is_search() ) { /* translators: 1: separator, 2: search phrase */ - $title = sprintf(__('Search Results %1$s %2$s'), $t_sep, strip_tags($search)); + $title = sprintf( __( 'Search Results %1$s %2$s' ), $t_sep, strip_tags( $search ) ); } // If it's a 404 page if ( is_404() ) { - $title = __('Page not found'); + $title = __( 'Page not found' ); } $prefix = ''; - if ( !empty($title) ) + 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 + // 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; + $title = implode( " $sep ", $title_array ) . $prefix; } else { - $title_array = explode( $t_sep, $title ); $title = $prefix . implode( " $sep ", $title_array ); } @@ -850,18 +1098,18 @@ function wp_title($sep = '»', $display = true, $seplocation = '') { * * @since 2.0.0 * - * @param string $title Page title. - * @param string $sep Title separator. + * @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 ) + if ( $display ) { echo $title; - else + } else { return $title; - + } } /** @@ -876,11 +1124,11 @@ function wp_title($sep = '»', $display = true, $seplocation = '') { * * @since 0.71 * - * @param string $prefix Optional. What to display before the title. - * @param bool $display Optional, default is true. Whether to display or retrieve title. - * @return string|null Title when retrieving, null when displaying or failure. + * @param string $prefix Optional. What to display before the title. + * @param bool $display Optional, default is true. Whether to display or retrieve title. + * @return string|void Title when retrieving. */ -function single_post_title($prefix = '', $display = true) { +function single_post_title( $prefix = '', $display = true ) { $_post = get_queried_object(); if ( !isset($_post->post_title) ) @@ -909,9 +1157,9 @@ function single_post_title($prefix = '', $display = true) { * * @since 3.1.0 * - * @param string $prefix Optional. What to display before the title. - * @param bool $display Optional, default is true. Whether to display or retrieve title. - * @return string|null Title when retrieving, null when displaying or failure. + * @param string $prefix Optional. What to display before the title. + * @param bool $display Optional, default is true. Whether to display or retrieve title. + * @return string|void Title when retrieving, null when displaying or failure. */ function post_type_archive_title( $prefix = '', $display = true ) { if ( ! is_post_type_archive() ) @@ -942,19 +1190,15 @@ function post_type_archive_title( $prefix = '', $display = true ) { /** * Display or retrieve page title for category archive. * - * This is useful for category template file or files, because it is optimized - * for category page title and with less overhead than {@link wp_title()}. - * - * It does not support placing the separator after the title, but by leaving the - * prefix parameter empty, you can set the title separator manually. The prefix - * does not automatically place a space between the prefix, so if there should - * be a space, the parameter value will need to have it at the end. + * Useful for category template files for displaying the category page title. + * The prefix does not automatically place a space between the prefix, so if + * there should be a space, the parameter value will need to have it at the end. * * @since 0.71 * - * @param string $prefix Optional. What to display before the title. - * @param bool $display Optional, default is true. Whether to display or retrieve title. - * @return string|null Title when retrieving, null when displaying or failure. + * @param string $prefix Optional. What to display before the title. + * @param bool $display Optional, default is true. Whether to display or retrieve title. + * @return string|void Title when retrieving. */ function single_cat_title( $prefix = '', $display = true ) { return single_term_title( $prefix, $display ); @@ -963,19 +1207,15 @@ function single_cat_title( $prefix = '', $display = true ) { /** * Display or retrieve page title for tag post archive. * - * Useful for tag template files for displaying the tag page title. It has less - * overhead than {@link wp_title()}, because of its limited implementation. - * - * It does not support placing the separator after the title, but by leaving the - * prefix parameter empty, you can set the title separator manually. The prefix + * Useful for tag template files for displaying the tag page title. The prefix * does not automatically place a space between the prefix, so if there should * be a space, the parameter value will need to have it at the end. * * @since 2.3.0 * - * @param string $prefix Optional. What to display before the title. - * @param bool $display Optional, default is true. Whether to display or retrieve title. - * @return string|null Title when retrieving, null when displaying or failure. + * @param string $prefix Optional. What to display before the title. + * @param bool $display Optional, default is true. Whether to display or retrieve title. + * @return string|void Title when retrieving. */ function single_tag_title( $prefix = '', $display = true ) { return single_term_title( $prefix, $display ); @@ -985,18 +1225,14 @@ function single_tag_title( $prefix = '', $display = true ) { * Display or retrieve page title for taxonomy term archive. * * Useful for taxonomy term template files for displaying the taxonomy term page title. - * It has less overhead than {@link wp_title()}, because of its limited implementation. - * - * It does not support placing the separator after the title, but by leaving the - * prefix parameter empty, you can set the title separator manually. The prefix - * does not automatically place a space between the prefix, so if there should + * The prefix does not automatically place a space between the prefix, so if there should * be a space, the parameter value will need to have it at the end. * * @since 3.1.0 * - * @param string $prefix Optional. What to display before the title. - * @param bool $display Optional, default is true. Whether to display or retrieve title. - * @return string|null Title when retrieving, null when displaying or failure. + * @param string $prefix Optional. What to display before the title. + * @param bool $display Optional, default is true. Whether to display or retrieve title. + * @return string|void Title when retrieving. */ function single_term_title( $prefix = '', $display = true ) { $term = get_queried_object(); @@ -1047,20 +1283,18 @@ function single_term_title( $prefix = '', $display = true ) { /** * Display or retrieve page title for post archive based on date. * - * Useful for when the template only needs to display the month and year, if - * either are available. Optimized for just this purpose, so if it is all that - * is needed, should be better than {@link wp_title()}. - * - * It does not support placing the separator after the title, but by leaving the - * prefix parameter empty, you can set the title separator manually. The prefix - * does not automatically place a space between the prefix, so if there should - * be a space, the parameter value will need to have it at the end. + * Useful for when the template only needs to display the month and year, + * if either are available. The prefix does not automatically place a space + * between the prefix, so if there should be a space, the parameter value + * will need to have it at the end. * * @since 0.71 * - * @param string $prefix Optional. What to display before the title. - * @param bool $display Optional, default is true. Whether to display or retrieve title. - * @return string|null Title when retrieving, null when displaying or failure. + * @global WP_Locale $wp_locale + * + * @param string $prefix Optional. What to display before the title. + * @param bool $display Optional, default is true. Whether to display or retrieve title. + * @return string|void Title when retrieving. */ function single_month_title($prefix = '', $display = true ) { global $wp_locale; @@ -1087,6 +1321,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. * @@ -1095,7 +1444,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. * @@ -1113,11 +1462,13 @@ function single_month_title($prefix = '', $display = true ) { * * @since 1.0.0 * - * @param string $url URL to archive. - * @param string $text Archive text description. + * @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. * @param string $before Optional. - * @param string $after Optional. + * @param string $after Optional. * @return string HTML link content for archive. */ function get_archives_link($url, $text, $format = 'html', $before = '', $after = '') { @@ -1140,39 +1491,45 @@ function get_archives_link($url, $text, $format = 'html', $before = '', $after = * * @param string $link_html The archive HTML link content. */ - $link_html = apply_filters( 'get_archives_link', $link_html ); - - return $link_html; + return apply_filters( 'get_archives_link', $link_html ); } /** * 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. - * @return string|null String when retrieving, null when displaying. - */ -function wp_get_archives($args = '') { + * @since 4.4.0 $post_type arg was added. + * + * @see get_archives_link() + * + * @global wpdb $wpdb + * @global WP_Locale $wp_locale + * + * @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' (`