X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/d3b1ea255664edd2deef17f900a655613d20820d..53f4633144ed68c8b8fb5861f992b5489894a940:/wp-includes/general-template.php?ds=sidebyside diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php index 68c73ced..8f2cdf67 100644 --- a/wp-includes/general-template.php +++ b/wp-includes/general-template.php @@ -10,87 +10,165 @@ * Load header template. * * Includes the header template for a theme or if a name is specified then a - * specialised header will be included. If the theme contains no header.php file - * then the header from the default theme will be included. + * specialised header will be included. * * 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(); - if ( isset($name) ) + $name = (string) $name; + if ( '' !== $name ) $templates[] = "header-{$name}.php"; - $templates[] = "header.php"; + $templates[] = 'header.php'; + // Backward compat code will be removed in a future release if ('' == locate_template($templates, true)) - load_template( get_theme_root() . '/default/header.php'); + load_template( ABSPATH . WPINC . '/theme-compat/header.php'); } /** * Load footer template. * * Includes the footer template for a theme or if a name is specified then a - * specialised footer will be included. If the theme contains no footer.php file - * then the footer from the default theme will be included. + * specialised footer will be included. * * 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(); - if ( isset($name) ) + $name = (string) $name; + if ( '' !== $name ) $templates[] = "footer-{$name}.php"; - $templates[] = "footer.php"; + $templates[] = 'footer.php'; + // Backward compat code will be removed in a future release if ('' == locate_template($templates, true)) - load_template( get_theme_root() . '/default/footer.php'); + load_template( ABSPATH . WPINC . '/theme-compat/footer.php'); } /** * Load sidebar template. * * Includes the sidebar template for a theme or if a name is specified then a - * specialised sidebar will be included. If the theme contains no sidebar.php - * file then the sidebar from the default theme will be included. + * specialised sidebar will be included. * * 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(); - if ( isset($name) ) + $name = (string) $name; + if ( '' !== $name ) $templates[] = "sidebar-{$name}.php"; - $templates[] = "sidebar.php"; + $templates[] = 'sidebar.php'; + // Backward compat code will be removed in a future release if ('' == locate_template($templates, true)) - load_template( get_theme_root() . '/default/sidebar.php'); + load_template( ABSPATH . WPINC . '/theme-compat/sidebar.php'); +} + +/** + * Load a template part into a template + * + * Makes it easy for a theme to reuse sections of code in a easy to overload way + * for child themes. + * + * Includes the named template part for a theme or if a name is specified then a + * specialised part will be included. If the theme contains no {slug}.php file + * then no template will be included. + * + * The template is included using require, not require_once, so you may include the + * same template part multiple times. + * + * For the $name parameter, if the file is called "{slug}-special.php" then specify + * "special". + * + * @since 3.0.0 + * + * @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(); + $name = (string) $name; + if ( '' !== $name ) + $templates[] = "{$slug}-{$name}.php"; + + $templates[] = "{$slug}.php"; + + locate_template($templates, true, false); } /** @@ -106,115 +184,319 @@ function get_sidebar( $name = null ) { * form into the sidebar and also by the search widget in WordPress. * * There is also an action that is called whenever the function is run called, - * 'get_search_form'. This can be useful for outputting JavaScript that the + * 'pre_get_search_form'. This can be useful for outputting JavaScript that the * search relies on or various formatting that applies to the beginning of the * search. To give a few examples of what it can be used for. * * @since 2.7.0 + * + * @param bool $echo Default to echo and not return the form. + * @return string|void String when $echo is false. */ -function get_search_form() { - do_action( 'get_search_form' ); - - $search_form_template = locate_template(array('searchform.php')); +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' ); if ( '' != $search_form_template ) { - require($search_form_template); - return; + ob_start(); + require( $search_form_template ); + $form = ob_get_clean(); + } else { + if ( 'html5' == $format ) { + $form = ''; + } else { + $form = ''; + } } - $form = ''; + /** + * 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; - echo apply_filters('get_search_form', $form); + if ( $echo ) + echo $result; + else + return $result; } /** * Display the Log In/Out link. * - * Displays a link, which allows the user to navigate to the Log In page to log in - * or log out depending on whether or not they are currently logged in. + * Displays a link, which allows users to navigate to the Log In page to log in + * 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 bool $echo Default to echo and not return the link. + * @return string|void String when retrieving. */ -function wp_loginout($redirect = '') { +function wp_loginout($redirect = '', $echo = true) { if ( ! is_user_logged_in() ) $link = '' . __('Log in') . ''; else $link = '' . __('Log out') . ''; - echo 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 ); + } } /** * Returns the Log Out URL. * - * Returns the URL that allows the user to log out of the site + * Returns the URL that allows the user to log out of the site. * - * @since 2.7 - * @uses wp_nonce_url() To protect against CSRF - * @uses site_url() To generate the log in URL - * @uses apply_filters() calls 'logout_url' hook on final logout url + * @since 2.7.0 * * @param string $redirect Path to redirect to on logout. + * @return string A log out URL. */ function wp_logout_url($redirect = '') { $args = array( 'action' => 'logout' ); if ( !empty($redirect) ) { - $args['redirect_to'] = $redirect; + $args['redirect_to'] = urlencode( $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 ); } /** - * Returns the Log In URL. + * Returns the URL that allows the user to log in to the site. * - * Returns the URL that allows the user to log in to the site - * - * @since 2.7 - * @uses site_url() To generate the log in URL - * @uses apply_filters() calls 'login_url' hook on final login url + * @since 2.7.0 * - * @param string $redirect Path to redirect to on login. + * @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 = '') { +function wp_login_url($redirect = '', $force_reauth = false) { $login_url = site_url('wp-login.php', 'login'); - if ( !empty($redirect) ) { + if ( !empty($redirect) ) $login_url = add_query_arg('redirect_to', urlencode($redirect), $login_url); - } - return apply_filters('login_url', $login_url, $redirect); + if ( $force_reauth ) + $login_url = add_query_arg('reauth', '1', $login_url); + + /** + * 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 ); } /** - * Returns the Lost Password URL. + * Returns the URL that allows the user to register on the site. + * + * @since 3.6.0 * + * @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' ) ); +} + +/** + * 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. + * + * @since 3.0.0 + * + * @param array $args Configuration options to modify the form output. + * @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 + 'form_id' => 'loginform', + 'label_username' => __( 'Username' ), + 'label_password' => __( 'Password' ), + 'label_remember' => __( 'Remember Me' ), + 'label_log_in' => __( 'Log In' ), + 'id_username' => 'user_login', + 'id_password' => 'user_pass', + 'id_remember' => 'rememberme', + 'id_submit' => 'wp-submit', + 'remember' => true, + '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 = ' +
+ ' . $login_form_top . ' +

+ + +

+

+ + +

+ ' . $login_form_middle . ' + ' . ( $args['remember'] ? '

' : '' ) . ' +

+ + +

+ ' . $login_form_bottom . ' +
'; + + if ( $args['echo'] ) + echo $form; + else + return $form; +} + +/** * 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. */ -function wp_lostpassword_url($redirect = '') { +function wp_lostpassword_url( $redirect = '' ) { $args = array( 'action' => 'lostpassword' ); if ( !empty($redirect) ) { $args['redirect_to'] = $redirect; } - $lostpassword_url = add_query_arg($args, site_url('wp-login.php', 'login')); - return apply_filters('lostpassword_url', $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 ); } /** @@ -224,23 +506,39 @@ 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 bool $echo Default to echo and not return the link. + * @return string|void String when retrieving. */ -function wp_register( $before = '
  • ', $after = '
    • ' ) { - +function wp_register( $before = '
  • ', $after = '
    • ', $echo = true ) { if ( ! is_user_logged_in() ) { if ( get_option('users_can_register') ) - $link = $before . '' . __('Register') . '' . $after; + $link = $before . '' . __('Register') . '' . $after; else $link = ''; } else { $link = $before . '' . __('Site Admin') . '' . $after; } - echo 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; + } } /** @@ -250,11 +548,16 @@ function wp_register( $before = '
  • ', $after = '
    • ' ) { * 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' ); } /** @@ -265,49 +568,53 @@ function wp_meta() { * * @param string $show What to display. */ -function bloginfo($show='') { - echo get_bloginfo($show, 'display'); +function bloginfo( $show='' ) { + echo get_bloginfo( $show, 'display' ); } /** * Retrieve information about the blog. * * Some show parameter values are deprecated and will be removed in future - * versions. Care should be taken to check the function contents and know what - * the deprecated blog info options are. Options without "// DEPRECATED" are - * the preferred and recommended ways to get the information. + * 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 * comment feeds can be retrieved from the 'comments_atom_url' (Atom comment * feed) or 'comments_rss2_url' (RSS 2.0 comment feed). * - * There are many other options and you should check the function contents: - * {@source 32 37} - * * @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 'url' : +function get_bloginfo( $show = '', $filter = 'raw' ) { + switch( $show ) { case 'home' : // DEPRECATED case 'siteurl' : // DEPRECATED - $output = get_option('home'); + _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; case 'wpurl' : - $output = get_option('siteurl'); + $output = site_url(); break; case 'description': $output = get_option('blogdescription'); @@ -331,7 +638,7 @@ function get_bloginfo($show = '', $filter = 'raw') { $output = get_feed_link('comments_rss2'); break; case 'pingback_url': - $output = get_option('siteurl') .'/xmlrpc.php'; + $output = site_url( 'xmlrpc.php' ); break; case 'stylesheet_url': $output = get_stylesheet_uri(); @@ -362,8 +669,18 @@ function get_bloginfo($show = '', $filter = 'raw') { $output = str_replace('_', '-', $output); break; case 'text_direction': - global $wp_locale; - $output = $wp_locale->text_direction; + _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 { + $output = 'ltr'; + } break; case 'name': default: @@ -378,15 +695,105 @@ 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; } +/** + * Returns the Site Icon URL. + * + * @param int $size Size of the site icon. + * @param string $url Fallback url if no site icon is found. + * @param int $blog_id Id of the blog to get the site icon for. + * @return string Site Icon URL. + */ +function get_site_icon_url( $size = 512, $url = '', $blog_id = 0 ) { + if ( $blog_id && is_multisite() ) { + $site_icon_id = get_blog_option( $blog_id, 'site_icon' ); + } else { + $site_icon_id = get_option( 'site_icon' ); + } + + if ( $site_icon_id ) { + if ( $size >= 512 ) { + $size_data = 'full'; + } else { + $size_data = array( $size, $size ); + } + $url_data = wp_get_attachment_image_src( $site_icon_id, $size_data ); + if ( $url_data ) { + $url = $url_data[0]; + } + } + + return $url; +} + +/** + * Displays the Site Icon URL. + * + * @param int $size Size of the site icon. + * @param string $url Fallback url if no site icon is found. + * @param int $blog_id Id of the blog to get the site icon for. + */ +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. + * + * @param int $blog_id Optional. Blog ID. Default: Current blog. + * @return bool + */ +function has_site_icon( $blog_id = 0 ) { + return (bool) get_site_icon_url( 512, '', $blog_id ); +} + +/** + * 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. * @@ -404,19 +811,18 @@ 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 + * @global int $page + * @global int $paged + * + * @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. + * @return string|void String on retrieve. */ -function wp_title($sep = '»', $display = true, $seplocation = '') { - global $wpdb, $wp_locale, $wp_query; +function wp_title( $sep = '»', $display = true, $seplocation = '' ) { + global $wp_locale, $page, $paged; - $cat = get_query_var('cat'); - $tag = get_query_var('tag_id'); - $category_name = get_query_var('category_name'); - $author = get_query_var('author'); - $author_name = get_query_var('author_name'); $m = get_query_var('m'); $year = get_query_var('year'); $monthnum = get_query_var('monthnum'); @@ -426,80 +832,70 @@ function wp_title($sep = '»', $display = true, $seplocation = '') { $t_sep = '%WP_TITILE_SEP%'; // Temporary separator, for accurate flipping, if necessary - // If there's a category - if ( !empty($cat) ) { - // category exclusion - if ( !stristr($cat,'-') ) - $title = apply_filters('single_cat_title', get_the_category_by_ID($cat)); - } elseif ( !empty($category_name) ) { - if ( stristr($category_name,'/') ) { - $category_name = explode('/',$category_name); - if ( $category_name[count($category_name)-1] ) - $category_name = $category_name[count($category_name)-1]; // no trailing slash - else - $category_name = $category_name[count($category_name)-2]; // there was a trailling slash - } - $cat = get_term_by('slug', $category_name, 'category', OBJECT, 'display'); - if ( $cat ) - $title = apply_filters('single_cat_title', $cat->name); + // If there is a post + if ( is_single() || ( is_home() && !is_front_page() ) || ( is_page() && !is_front_page() ) ) { + $title = single_post_title( '', false ); } - if ( !empty($tag) ) { - $tag = get_term($tag, 'post_tag', OBJECT, 'display'); - if ( is_wp_error( $tag ) ) - return $tag; - if ( ! empty($tag->name) ) - $title = apply_filters('single_tag_title', $tag->name); + // If there's a post type archive + if ( is_post_type_archive() ) { + $post_type = get_query_var( '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 ) + $title = post_type_archive_title( '', false ); } - // If there's an author - if ( !empty($author) ) { - $title = get_userdata($author); - $title = $title->display_name; + // If there's a category or tag + if ( is_category() || is_tag() ) { + $title = single_term_title( '', false ); + } + + // If there's a taxonomy + if ( is_tax() ) { + $term = get_queried_object(); + if ( $term ) { + $tax = get_taxonomy( $term->taxonomy ); + $title = single_term_title( $tax->labels->name . $t_sep, false ); + } } - if ( !empty($author_name) ) { - // We do a direct query here because we don't cache by nicename. - $title = $wpdb->get_var($wpdb->prepare("SELECT display_name FROM $wpdb->users WHERE user_nicename = %s", $author_name)); + + // If there's an author + if ( is_author() && ! is_post_type_archive() ) { + $author = get_queried_object(); + 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 ) + $title = post_type_archive_title( '', false ); + // If there's a month - if ( !empty($m) ) { + 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" : ""); + $title = $my_year . ( $my_month ? $t_sep . $my_month : '' ) . ( $my_day ? $t_sep . $my_day : '' ); } - if ( !empty($year) ) { + // If there's a year + if ( is_archive() && !empty($year) ) { $title = $year; if ( !empty($monthnum) ) - $title .= "$t_sep" . $wp_locale->get_month($monthnum); + $title .= $t_sep . $wp_locale->get_month($monthnum); if ( !empty($day) ) - $title .= "$t_sep" . zeroise($day, 2); - } - - // If there is a post - if ( is_single() || ( is_home() && !is_front_page() ) || ( is_page() && !is_front_page() ) ) { - $post = $wp_query->get_queried_object(); - $title = strip_tags( apply_filters( 'single_post_title', $post->post_title ) ); - } - - // If there's a taxonomy - if ( is_tax() ) { - $taxonomy = get_query_var( 'taxonomy' ); - $tax = get_taxonomy( $taxonomy ); - $tax = $tax->label; - $term = $wp_query->get_queried_object(); - $term = $term->name; - $title = "$tax$t_sep$term"; + $title .= $t_sep . zeroise($day, 2); } - //If it's a search + // 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)); } + // If it's a 404 page if ( is_404() ) { $title = __('Page not found'); } @@ -508,17 +904,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 ) @@ -532,7 +957,6 @@ function wp_title($sep = '»', $display = true, $seplocation = '') { * Display or retrieve page title for post. * * This is optimized for single.php template file for displaying the post title. - * Only useful for posts, does not support pages for example. * * 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 @@ -540,28 +964,68 @@ function wp_title($sep = '»', $display = true, $seplocation = '') { * be a space, the parameter value will need to have it at the end. * * @since 0.71 - * @uses $wpdb - * - * @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. - */ -function single_post_title($prefix = '', $display = true) { - global $wpdb; - $p = get_query_var('p'); - $name = get_query_var('name'); - - if ( intval($p) || '' != $name ) { - if ( !$p ) - $p = $wpdb->get_var($wpdb->prepare("SELECT ID FROM $wpdb->posts WHERE post_name = %s", $name)); - $post = & get_post($p); - $title = $post->post_title; - $title = apply_filters('single_post_title', $title); - if ( $display ) - echo $prefix.strip_tags($title); - else - return strip_tags($title); - } + * + * @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 ) { + $_post = get_queried_object(); + + if ( !isset($_post->post_title) ) + return; + + /** + * 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 + return $prefix . $title; +} + +/** + * Display or retrieve title for a post type archive. + * + * This is optimized for archive.php and archive-{$post_type}.php template files + * for displaying the title of the post type. + * + * @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|void Title when retrieving, null when displaying or failure. + */ +function post_type_archive_title( $prefix = '', $display = true ) { + if ( ! is_post_type_archive() ) + return; + + $post_type = get_query_var( 'post_type' ); + if ( is_array( $post_type ) ) + $post_type = reset( $post_type ); + + $post_type_obj = get_post_type_object( $post_type ); + + /** + * 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; + else + return $prefix . $title; } /** @@ -577,23 +1041,12 @@ function single_post_title($prefix = '', $display = true) { * * @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. - */ -function single_cat_title($prefix = '', $display = true ) { - $cat = intval( get_query_var('cat') ); - if ( !empty($cat) && !(strtoupper($cat) == 'ALL') ) { - $my_cat_name = apply_filters('single_cat_title', get_the_category_by_ID($cat)); - if ( !empty($my_cat_name) ) { - if ( $display ) - echo $prefix.strip_tags($my_cat_name); - else - return strip_tags($my_cat_name); - } - } else if ( is_tag() ) { - return single_tag_title($prefix, $display); - } + * @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 ); } /** @@ -609,28 +1062,75 @@ function single_cat_title($prefix = '', $display = true ) { * * @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 ) { - if ( !is_tag() ) +function single_tag_title( $prefix = '', $display = true ) { + return single_term_title( $prefix, $display ); +} + +/** + * 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 + * 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|void Title when retrieving. + */ +function single_term_title( $prefix = '', $display = true ) { + $term = get_queried_object(); + + if ( !$term ) return; - $tag_id = intval( get_query_var('tag_id') ); - - if ( !empty($tag_id) ) { - $my_tag = &get_term($tag_id, 'post_tag', OBJECT, 'display'); - if ( is_wp_error( $my_tag ) ) - return false; - $my_tag_name = apply_filters('single_tag_title', $my_tag->name); - if ( !empty($my_tag_name) ) { - if ( $display ) - echo $prefix . $my_tag_name; - else - return $my_tag_name; - } + 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() ) { + /** + * 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() ) { + /** + * 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 { + return; } + + if ( empty( $term_name ) ) + return; + + if ( $display ) + echo $prefix . $term_name; + else + return $prefix . $term_name; } /** @@ -647,9 +1147,11 @@ function single_tag_title($prefix = '', $display = true ) { * * @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; @@ -676,6 +1178,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. * @@ -684,7 +1301,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. * @@ -701,80 +1318,96 @@ function single_month_title($prefix = '', $display = true ) { * three values for the format are not used, then custom format is assumed. * * @since 1.0.0 - * @author Orien - * @link http://icecode.com/ link navigation hack by Orien * - * @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 = '') { $text = wptexturize($text); - $title_text = esc_attr($text); $url = esc_url($url); if ('link' == $format) - $link_html = "\t\n"; + $link_html = "\t\n"; elseif ('option' == $format) $link_html = "\t\n"; elseif ('html' == $format) - $link_html = "\t
  • $before$text$after
    • \n"; + $link_html = "\t
  • $before$text$after
    • \n"; else // custom - $link_html = "\t$before$text$after\n"; - - $link_html = apply_filters( "get_archives_link", $link_html ); - - return $link_html; + $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. + */ + 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. + * @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' (`