WordPress.org

Make WordPress Core


Ignore:
Timestamp:
10/20/2015 04:20:04 PM (4 years ago)
Author:
obenland
Message:

Themes: Improve document title output.

Introduces more flexibility in filtering all parts of the document title,the
separator, and a way to short-circuit title generation. Plugins can now also
check for theme support and reliably filter the entire output. See #18548.
Deprecates wp_title().

Fixes #31078.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/general-template.php

    r35105 r35294  
    782782
    783783/**
    784  * Display title tag with contents.
     784 * Returns document title for the current page.
     785 *
     786 * @since 4.4.0
     787 *
     788 * @global int $page  Page number of a single post.
     789 * @global int $paged Page number of a list of posts.
     790 *
     791 * @return string Tag with the document title.
     792 */
     793function wp_get_document_title() {
     794
     795    /**
     796     * Allows to short-circuit the title generation.
     797     *
     798     * @since 4.4.0
     799     *
     800     * @param string $title The document title. Default empty string.
     801     */
     802    $title = apply_filters( 'pre_get_document_title', '' );
     803    if ( ! empty( $title ) ) {
     804        return $title;
     805    }
     806
     807    global $page, $paged;
     808
     809    $title = array(
     810        'title' => '',
     811    );
     812
     813    if ( is_home() && is_front_page() ) {
     814        $title['title'] = get_bloginfo( 'name', 'display' );
     815
     816        /*
     817         * If we're on the blog page and that page is not the homepage or a single page that is designated as
     818         * the homepage, use the container page's title.
     819         */
     820    } elseif ( ( is_home() && ! is_front_page() ) || ( ! is_home() && is_front_page() ) ) {
     821        $title['title'] = single_post_title( '', false );
     822
     823        // If we're on a post / page.
     824    } elseif ( is_singular() ) {
     825        $title['title'] = single_post_title( '', false );
     826
     827        // If we're on a category or tag or taxonomy archive.
     828    } elseif ( is_category() || is_tag() || is_tax() ) {
     829        $title['title'] = single_term_title( '', false );
     830
     831        // If it's a search.
     832    } elseif ( is_search() ) {
     833        /* translators: %s: search phrase */
     834        $title['title'] = sprintf( __( 'Search Results for “%s”' ), get_search_query() );
     835
     836        // If we're on an author archive.
     837    } elseif ( is_author() && $author = get_queried_object() ) {
     838        $title['title'] = $author->display_name;
     839
     840        // If we're on a post type archive.
     841    } elseif ( is_post_type_archive() ) {
     842        $title['title'] = post_type_archive_title( '', false );
     843
     844        // If it's a date archive.
     845    } elseif ( is_year() ) {
     846        $title['title'] = get_the_date( _x( 'Y', 'yearly archives date format' ) );
     847
     848    } elseif ( is_month() ) {
     849        $title['title'] = get_the_date( _x( 'F Y', 'monthly archives date format' ) );
     850
     851    } elseif ( is_day() ) {
     852        $title['title'] = get_the_date();
     853
     854        // If it's a 404 page.
     855    } elseif ( is_404() ) {
     856        $title['title'] = __( 'Page not found' );
     857    }
     858
     859    // Add a page number if necessary.
     860    if ( ( $paged >= 2 || $page >= 2 ) && ! is_404() ) {
     861        $title['page'] = sprintf( __( 'Page %s' ), max( $paged, $page ) );
     862    }
     863
     864    // Append the description or site title to give context.
     865    if ( is_home() && is_front_page() ) {
     866        $title['tagline'] = get_bloginfo( 'description', 'display' );
     867    } else {
     868        $title['site'] = get_bloginfo( 'name', 'display' );
     869    }
     870
     871    /**
     872     * Filters the separator for the document title.
     873     *
     874     * @since 4.4.0
     875     *
     876     * @param string $sep The separator. Default '-'.
     877     */
     878    $sep = apply_filters( 'document_title_separator', '-' );
     879
     880    /**
     881     * Filters the parts of the document title.
     882     *
     883     * @since 4.4.0
     884     *
     885     * @param array $title {
     886     *     The document title parts.
     887     *
     888     *     @type string $title   Title of the viewed page.
     889     *     @type string $page    Optional. Page number if paginated.
     890     *     @type string $tagline Optional. Site description when on home page.
     891     *     @type string $site    Optional. Site title when not on home page.
     892     * }
     893     */
     894    $title = apply_filters( 'document_title_parts', $title );
     895
     896    $title = implode( " $sep ", array_filter( $title ) );
     897    $title = wptexturize( $title );
     898    $title = convert_chars( $title );
     899    $title = esc_html( $title );
     900    $title = capital_P_dangit( $title );
     901
     902    return $title;
     903}
     904
     905/**
     906 * Displays title tag with content.
    785907 *
    786908 * @ignore
    787909 * @since 4.1.0
     910 * @since 4.4.0 Improved title output replaced `wp_title()`.
    788911 * @access private
    789  *
    790  * @see wp_title()
    791912 */
    792913function _wp_render_title_tag() {
     
    795916    }
    796917
    797     // This can only work internally on wp_head.
    798     if ( ! did_action( 'wp_head' ) && ! doing_action( 'wp_head' ) ) {
    799         return;
    800     }
    801 
    802     echo '<title>' . wp_title( '|', false, 'right' ) . "</title>\n";
    803 }
    804 
    805 /**
    806  * Display or retrieve page title for all areas of blog.
    807  *
    808  * By default, the page title will display the separator before the page title,
    809  * so that the blog title will be before the page title. This is not good for
    810  * title display, since the blog title shows up on most tabs and not what is
    811  * important, which is the page that the user is looking at.
    812  *
    813  * There are also SEO benefits to having the blog title after or to the 'right'
    814  * or the page title. However, it is mostly common sense to have the blog title
    815  * to the right with most browsers supporting tabs. You can achieve this by
    816  * using the seplocation parameter and setting the value to 'right'. This change
    817  * was introduced around 2.5.0, in case backwards compatibility of themes is
    818  * important.
    819  *
    820  * @since 1.0.0
    821  *
    822  * @global WP_Locale $wp_locale
    823  * @global int       $page
    824  * @global int       $paged
    825  *
    826  * @param string $sep         Optional, default is '&raquo;'. How to separate the various items within the page title.
    827  * @param bool   $display     Optional, default is true. Whether to display or retrieve title.
    828  * @param string $seplocation Optional. Direction to display title, 'right'.
    829  * @return string|void String on retrieve.
    830  */
    831 function wp_title( $sep = '&raquo;', $display = true, $seplocation = '' ) {
    832     global $wp_locale, $page, $paged;
    833 
    834     $m = get_query_var('m');
    835     $year = get_query_var('year');
    836     $monthnum = get_query_var('monthnum');
    837     $day = get_query_var('day');
    838     $search = get_query_var('s');
    839     $title = '';
    840 
    841     $t_sep = '%WP_TITILE_SEP%'; // Temporary separator, for accurate flipping, if necessary
    842 
    843     // If there is a post
    844     if ( is_single() || ( is_home() && !is_front_page() ) || ( is_page() && !is_front_page() ) ) {
    845         $title = single_post_title( '', false );
    846     }
    847 
    848     // If there's a post type archive
    849     if ( is_post_type_archive() ) {
    850         $post_type = get_query_var( 'post_type' );
    851         if ( is_array( $post_type ) )
    852             $post_type = reset( $post_type );
    853         $post_type_object = get_post_type_object( $post_type );
    854         if ( ! $post_type_object->has_archive )
    855             $title = post_type_archive_title( '', false );
    856     }
    857 
    858     // If there's a category or tag
    859     if ( is_category() || is_tag() ) {
    860         $title = single_term_title( '', false );
    861     }
    862 
    863     // If there's a taxonomy
    864     if ( is_tax() ) {
    865         $term = get_queried_object();
    866         if ( $term ) {
    867             $tax = get_taxonomy( $term->taxonomy );
    868             $title = single_term_title( $tax->labels->name . $t_sep, false );
    869         }
    870     }
    871 
    872     // If there's an author
    873     if ( is_author() && ! is_post_type_archive() ) {
    874         $author = get_queried_object();
    875         if ( $author )
    876             $title = $author->display_name;
    877     }
    878 
    879     // Post type archives with has_archive should override terms.
    880     if ( is_post_type_archive() && $post_type_object->has_archive )
    881         $title = post_type_archive_title( '', false );
    882 
    883     // If there's a month
    884     if ( is_archive() && !empty($m) ) {
    885         $my_year = substr($m, 0, 4);
    886         $my_month = $wp_locale->get_month(substr($m, 4, 2));
    887         $my_day = intval(substr($m, 6, 2));
    888         $title = $my_year . ( $my_month ? $t_sep . $my_month : '' ) . ( $my_day ? $t_sep . $my_day : '' );
    889     }
    890 
    891     // If there's a year
    892     if ( is_archive() && !empty($year) ) {
    893         $title = $year;
    894         if ( !empty($monthnum) )
    895             $title .= $t_sep . $wp_locale->get_month($monthnum);
    896         if ( !empty($day) )
    897             $title .= $t_sep . zeroise($day, 2);
    898     }
    899 
    900     // If it's a search
    901     if ( is_search() ) {
    902         /* translators: 1: separator, 2: search phrase */
    903         $title = sprintf(__('Search Results %1$s %2$s'), $t_sep, strip_tags($search));
    904     }
    905 
    906     // If it's a 404 page
    907     if ( is_404() ) {
    908         $title = __('Page not found');
    909     }
    910 
    911     $prefix = '';
    912     if ( !empty($title) )
    913         $prefix = " $sep ";
    914 
    915     /**
    916      * Filter the parts of the page title.
    917      *
    918      * @since 4.0.0
    919      *
    920      * @param array $title_array Parts of the page title.
    921      */
    922     $title_array = apply_filters( 'wp_title_parts', explode( $t_sep, $title ) );
    923 
    924     // Determines position of the separator and direction of the breadcrumb
    925     if ( 'right' == $seplocation ) { // sep on right, so reverse the order
    926         $title_array = array_reverse( $title_array );
    927         $title = implode( " $sep ", $title_array ) . $prefix;
    928     } else {
    929         $title = $prefix . implode( " $sep ", $title_array );
    930     }
    931 
    932     if ( current_theme_supports( 'title-tag' ) && ! is_feed() ) {
    933         $title .= get_bloginfo( 'name', 'display' );
    934 
    935         $site_description = get_bloginfo( 'description', 'display' );
    936         if ( $site_description && ( is_home() || is_front_page() ) ) {
    937             $title .= " $sep $site_description";
    938         }
    939 
    940         if ( ( $paged >= 2 || $page >= 2 ) && ! is_404() ) {
    941             $title .= " $sep " . sprintf( __( 'Page %s' ), max( $paged, $page ) );
    942         }
    943     }
    944 
    945     /**
    946      * Filter the text of the page title.
    947      *
    948      * @since 2.0.0
    949      *
    950      * @param string $title       Page title.
    951      * @param string $sep         Title separator.
    952      * @param string $seplocation Location of the separator (left or right).
    953      */
    954     $title = apply_filters( 'wp_title', $title, $sep, $seplocation );
    955 
    956     // Send it out
    957     if ( $display )
    958         echo $title;
    959     else
    960         return $title;
    961 
     918    echo '<title>' . wp_get_document_title() . '</title>' . "\n";
    962919}
    963920
     
    1040997 * Display or retrieve page title for category archive.
    1041998 *
    1042  * This is useful for category template file or files, because it is optimized
    1043  * for category page title and with less overhead than {@link wp_title()}.
    1044  *
    1045  * It does not support placing the separator after the title, but by leaving the
    1046  * prefix parameter empty, you can set the title separator manually. The prefix
    1047  * does not automatically place a space between the prefix, so if there should
    1048  * be a space, the parameter value will need to have it at the end.
     999 * Useful for category template files for displaying the category page title.
     1000 * The prefix does not automatically place a space between the prefix, so if
     1001 * there should be a space, the parameter value will need to have it at the end.
    10491002 *
    10501003 * @since 0.71
     
    10611014 * Display or retrieve page title for tag post archive.
    10621015 *
    1063  * Useful for tag template files for displaying the tag page title. It has less
    1064  * overhead than {@link wp_title()}, because of its limited implementation.
    1065  *
    1066  * It does not support placing the separator after the title, but by leaving the
    1067  * prefix parameter empty, you can set the title separator manually. The prefix
     1016 * Useful for tag template files for displaying the tag page title. The prefix
    10681017 * does not automatically place a space between the prefix, so if there should
    10691018 * be a space, the parameter value will need to have it at the end.
     
    10831032 *
    10841033 * Useful for taxonomy term template files for displaying the taxonomy term page title.
    1085  * It has less overhead than {@link wp_title()}, because of its limited implementation.
    1086  *
    1087  * It does not support placing the separator after the title, but by leaving the
    1088  * prefix parameter empty, you can set the title separator manually. The prefix
    1089  * does not automatically place a space between the prefix, so if there should
     1034 * The prefix does not automatically place a space between the prefix, so if there should
    10901035 * be a space, the parameter value will need to have it at the end.
    10911036 *
     
    11451090 * Display or retrieve page title for post archive based on date.
    11461091 *
    1147  * Useful for when the template only needs to display the month and year, if
    1148  * either are available. Optimized for just this purpose, so if it is all that
    1149  * is needed, should be better than {@link wp_title()}.
    1150  *
    1151  * It does not support placing the separator after the title, but by leaving the
    1152  * prefix parameter empty, you can set the title separator manually. The prefix
    1153  * does not automatically place a space between the prefix, so if there should
    1154  * be a space, the parameter value will need to have it at the end.
     1092 * Useful for when the template only needs to display the month and year,
     1093 * if either are available. The prefix does not automatically place a space
     1094 * between the prefix, so if there should be a space, the parameter value
     1095 * will need to have it at the end.
    11551096 *
    11561097 * @since 0.71
Note: See TracChangeset for help on using the changeset viewer.