X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/41578db67d72562346e4dbb2a14889b23d522813..5d244c8fd9a27c9f89dd08da2af6fbc67d4fce63:/wp-includes/general-template.php diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php index f4d6f37d..56f4eec2 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 @@ -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. */ @@ -340,8 +329,6 @@ function wp_logout_url($redirect = '') { * * @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. * @return string A log in URL. @@ -373,8 +360,6 @@ function wp_login_url($redirect = '', $force_reauth = false) { * * @since 3.6.0 * - * @uses site_url() To generate the registration URL. - * * @return string User registration URL. */ function wp_registration_url() { @@ -496,8 +481,6 @@ function wp_login_form( $args = array() ) { * * @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,8 +511,8 @@ 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 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. */ @@ -544,21 +527,22 @@ function wp_register( $before = '
  • ', $after = '
    • ', $echo = true ) { $link = $before . '' . __('Site Admin') . '' . $after; } + /** + * 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 +554,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 +581,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 @@ -729,6 +713,28 @@ function get_bloginfo( $show = '', $filter = 'raw' ) { return $output; } +/** + * Display title tag with contents. + * + * @since 4.1.0 + * @access private + * @internal + * + * @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. * @@ -752,7 +758,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'); @@ -793,7 +799,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; @@ -835,16 +841,36 @@ 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 ); } + 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. * @@ -1087,6 +1113,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 +1236,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,6 +1254,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. @@ -1148,31 +1291,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' (`