X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/177fd6fefd2e3d5a0ea6591c71d660cabdb3c1a4..3d39054f012aefe514b3f5509e32f09fc4feda44:/wp-includes/general-template.php?ds=sidebyside diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php index 1b1baf30..a5d5ea7d 100644 --- a/wp-includes/general-template.php +++ b/wp-includes/general-template.php @@ -1,86 +1,664 @@ + + + '; + } else { + $form = ''; + } + } + + /** + * Filters 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; + + if ( $echo ) + echo $result; + else + return $result; +} -function wp_loginout() { +/** + * Display the Log In/Out link. + * + * 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 + * + * @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 = '', $echo = true) { if ( ! is_user_logged_in() ) - $link = '' . __('Log in') . ''; + $link = '' . __('Log in') . ''; else - $link = '' . __('Log out') . ''; + $link = '' . __('Log out') . ''; + + if ( $echo ) { + /** + * Filters 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 ); + } +} - echo apply_filters('loginout', $link); +/** + * Retrieves the logout URL. + * + * Returns the URL that allows the user to log out of the site. + * + * @since 2.7.0 + * + * @param string $redirect Path to redirect to on logout. + * @return string The logout URL. Note: HTML-encoded via esc_html() in wp_nonce_url(). + */ +function wp_logout_url($redirect = '') { + $args = array( 'action' => 'logout' ); + if ( !empty($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' ); + + /** + * Filters the logout URL. + * + * @since 2.8.0 + * + * @param string $logout_url The HTML-encoded logout URL. + * @param string $redirect Path to redirect to on logout. + */ + return apply_filters( 'logout_url', $logout_url, $redirect ); } +/** + * Retrieves the login URL. + * + * @since 2.7.0 + * + * @param string $redirect Path to redirect to on log in. + * @param bool $force_reauth Whether to force reauthorization, even if a cookie is present. + * Default false. + * @return string The login URL. Not HTML-encoded. + */ +function wp_login_url($redirect = '', $force_reauth = false) { + $login_url = site_url('wp-login.php', 'login'); + + if ( !empty($redirect) ) + $login_url = add_query_arg('redirect_to', urlencode($redirect), $login_url); + + if ( $force_reauth ) + $login_url = add_query_arg('reauth', '1', $login_url); + + /** + * Filters the login URL. + * + * @since 2.8.0 + * @since 4.2.0 The `$force_reauth` parameter was added. + * + * @param string $login_url The login URL. Not HTML-encoded. + * @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 URL that allows the user to register on the site. + * + * @since 3.6.0 + * + * @return string User registration URL. + */ +function wp_registration_url() { + /** + * Filters 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. + * + * 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 { + * 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 or email address field. Default 'Username or Email'. + * @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, + // 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 or Email' ), + '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' => '', + // Set 'value_remember' to true to default the "Remember me" checkbox to checked. + 'value_remember' => false, + ); + + /** + * Filters 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 ) ); + + /** + * Filters 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 ); + + /** + * Filters 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 ); + + /** + * Filters 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; +} -function wp_register( $before = '
  • ', $after = '
    • ' ) { +/** + * Returns the URL that allows the user to retrieve the lost password + * + * @since 2.8.0 + * + * @param string $redirect Path to redirect to on login. + * @return string Lost password URL. + */ +function wp_lostpassword_url( $redirect = '' ) { + $args = array( 'action' => 'lostpassword' ); + if ( !empty($redirect) ) { + $args['redirect_to'] = $redirect; + } + $lostpassword_url = add_query_arg( $args, network_site_url('wp-login.php', 'login') ); + + /** + * Filters 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 ); +} + +/** + * Display the Registration or Admin link. + * + * Display a link which allows the user to navigate to the registration page if + * not logged in and registration is enabled or to the dashboard if logged in. + * + * @since 1.5.0 + * + * @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; + $link = $before . '' . __('Register') . '' . $after; else $link = ''; + } elseif ( current_user_can( 'read' ) ) { + $link = $before . '' . __('Site Admin') . '' . $after; } else { - $link = $before . '' . __('Site Admin') . '' . $after; + $link = ''; } - echo apply_filters('register', $link); + /** + * Filters 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; + } } - +/** + * Theme container function for the 'wp_meta' action. + * + * The {@see 'wp_meta'} action can have several purposes, depending on how you use it, + * but one purpose might have been to allow for theme switching. + * + * @since 1.5.0 + * + * @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' ); } - -function bloginfo($show='') { - echo get_bloginfo($show, 'display'); +/** + * Displays information about the current site. + * + * @since 0.71 + * + * @see get_bloginfo() For possible `$show` values + * + * @param string $show Optional. Site information to display. Default empty. + */ +function bloginfo( $show = '' ) { + echo get_bloginfo( $show, 'display' ); } /** - * Note: some of these values are DEPRECATED. Meaning they could be - * taken out at any time and shouldn't be relied upon. Options - * without "// DEPRECATED" are the preferred and recommended ways - * to get the information. + * Retrieves information about the current site. + * + * Possible values for `$show` include: + * + * - 'name' - Site title (set in Settings > General) + * - 'description' - Site tagline (set in Settings > General) + * - 'wpurl' - The WordPress address (URL) (set in Settings > General) + * - 'url' - The Site address (URL) (set in Settings > General) + * - 'admin_email' - Admin email (set in Settings > General) + * - 'charset' - The "Encoding for pages and feeds" (set in Settings > Reading) + * - 'version' - The current WordPress version + * - 'html_type' - The content-type (default: "text/html"). Themes and plugins + * can override the default value using the {@see 'pre_option_html_type'} filter + * - 'text_direction' - The text direction determined by the site's language. is_rtl() + * should be used instead + * - 'language' - Language code for the current site + * - 'stylesheet_url' - URL to the stylesheet for the active theme. An active child theme + * will take precedence over this value + * - 'stylesheet_directory' - Directory path for the active theme. An active child theme + * will take precedence over this value + * - 'template_url' / 'template_directory' - URL of the active theme's directory. An active + * child theme will NOT take precedence over this value + * - 'pingback_url' - The pingback XML-RPC file URL (xmlrpc.php) + * - 'atom_url' - The Atom feed URL (/feed/atom) + * - 'rdf_url' - The RDF/RSS 1.0 feed URL (/feed/rfd) + * - 'rss_url' - The RSS 0.92 feed URL (/feed/rss) + * - 'rss2_url' - The RSS 2.0 feed URL (/feed) + * - 'comments_atom_url' - The comments Atom feed URL (/comments/feed) + * - 'comments_rss2_url' - The comments RSS 2.0 feed URL (/comments/feed) + * + * Some `$show` values are deprecated and will be removed in future versions. + * These options will trigger the _deprecated_argument() function. + * + * Deprecated arguments include: + * + * - 'siteurl' - Use 'url' instead + * - 'home' - Use 'url' instead + * + * @since 0.71 + * + * @global string $wp_version + * + * @param string $show Optional. Site info to retrieve. Default empty (site name). + * @param string $filter Optional. How to filter what is retrieved. Default 'raw'. + * @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.0', 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'); @@ -104,7 +682,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(); @@ -131,12 +709,29 @@ function get_bloginfo($show = '', $filter = 'raw') { $output = $wp_version; break; case 'language': - $output = get_locale(); - $output = str_replace('_', '-', $output); + /* translators: Translate this to the correct language tag for your locale, + * see https://www.w3.org/International/articles/language-tags/ for reference. + * Do not translate into your own language. + */ + $output = __( 'html_lang_attribute' ); + if ( 'html_lang_attribute' === $output || preg_match( '/[^a-zA-Z0-9-]/', $output ) ) { + $output = get_locale(); + $output = str_replace( '_', '-', $output ); + } break; case 'text_direction': - global $wp_locale; - $output = $wp_locale->text_direction; + _deprecated_argument( __FUNCTION__, '2.2.0', 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: @@ -151,165 +746,661 @@ 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 ) { + /** + * Filters 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 { + /** + * Filters 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. + * + * @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 ); + } -function wp_title($sep = '»', $display = true, $seplocation = '') { - global $wpdb, $wp_locale, $wp_query; + $site_icon_id = get_option( 'site_icon' ); - $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'); - $day = get_query_var('day'); - $title = ''; - - // 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 + if ( $site_icon_id ) { + if ( $size >= 512 ) { + $size_data = 'full'; + } else { + $size_data = array( $size, $size ); } - $cat = get_term_by('slug', $category_name, 'category', OBJECT, 'display'); - if ( $cat ) - $title = apply_filters('single_cat_title', $cat->name); + $url = wp_get_attachment_image_url( $site_icon_id, $size_data ); } - 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 ( is_multisite() && ms_is_switched() ) { + restore_current_blog(); + } + + /** + * Filters 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 ); +} + +/** + * Determines whether the site has a custom logo. + * + * @since 4.5.0 + * + * @param int $blog_id Optional. ID of the blog in question. Default is the ID of the current blog. + * @return bool Whether the site has a custom logo or not. + */ +function has_custom_logo( $blog_id = 0 ) { + if ( is_multisite() && (int) $blog_id !== get_current_blog_id() ) { + switch_to_blog( $blog_id ); + } + + $custom_logo_id = get_theme_mod( 'custom_logo' ); + + if ( is_multisite() && ms_is_switched() ) { + restore_current_blog(); + } + + return (bool) $custom_logo_id; +} + +/** + * Returns a custom logo, linked to home. + * + * @since 4.5.0 + * + * @param int $blog_id Optional. ID of the blog in question. Default is the ID of the current blog. + * @return string Custom logo markup. + */ +function get_custom_logo( $blog_id = 0 ) { + $html = ''; + + if ( is_multisite() && (int) $blog_id !== get_current_blog_id() ) { + switch_to_blog( $blog_id ); + } + + $custom_logo_id = get_theme_mod( 'custom_logo' ); + + // We have a logo. Logo is go. + if ( $custom_logo_id ) { + $html = sprintf( '', + esc_url( home_url( '/' ) ), + wp_get_attachment_image( $custom_logo_id, 'full', false, array( + 'class' => 'custom-logo', + 'itemprop' => 'logo', + ) ) + ); + } + + // If no logo is set but we're in the Customizer, leave a placeholder (needed for the live preview). + elseif ( is_customize_preview() ) { + $html = sprintf( '', + esc_url( home_url( '/' ) ) + ); + } + + if ( is_multisite() && ms_is_switched() ) { + restore_current_blog(); + } + + /** + * Filters the custom logo output. + * + * @since 4.5.0 + * @since 4.6.0 Added the `$blog_id` parameter. + * + * @param string $html Custom logo HTML output. + * @param int $blog_id ID of the blog to get the custom logo for. + */ + return apply_filters( 'get_custom_logo', $html, $blog_id ); +} + +/** + * Displays a custom logo, linked to home. + * + * @since 4.5.0 + * + * @param int $blog_id Optional. ID of the blog in question. Default is the ID of the current blog. + */ +function the_custom_logo( $blog_id = 0 ) { + echo get_custom_logo( $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() { + + /** + * Filters 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 front page, use the site title. + } elseif ( 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 that is not the homepage or + * a single post of any post type, use the post title. + */ + } elseif ( is_home() || 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_front_page() ) { + $title['tagline'] = get_bloginfo( 'description', 'display' ); + } else { + $title['site'] = get_bloginfo( 'name', 'display' ); + } + + /** + * Filters the separator for the document title. + * + * @since 4.4.0 + * + * @param string $sep Document title separator. Default '-'. + */ + $sep = apply_filters( 'document_title_separator', '-' ); + + /** + * Filters 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. + * + * By default, the page title will display the separator before the page title, + * so that the blog title will be before the page title. This is not good for + * title display, since the blog title shows up on most tabs and not what is + * important, which is the page that the user is looking at. + * + * There are also SEO benefits to having the blog title after or to the 'right' + * of the page title. However, it is mostly common sense to have the blog title + * to the right with most browsers supporting tabs. You can achieve this by + * using the seplocation parameter and setting the value to 'right'. This change + * was introduced around 2.5.0, in case backward compatibility of themes is + * important. + * + * @since 1.0.0 + * + * @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 $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 = ''; + + $t_sep = '%WP_TITLE_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() ) ) { + $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 ) ) { + $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 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 there's an author - if ( !empty($author) ) { - $title = get_userdata($author); - $title = $title->display_name; + if ( is_author() && ! is_post_type_archive() ) { + $author = get_queried_object(); + if ( $author ) { + $title = $author->display_name; + } } - 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)); + + // 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) ) { - $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 ? "$sep $my_month" : "") . ($my_day ? "$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 ( !empty($year) ) { + // If there's a year + if ( is_archive() && ! empty( $year ) ) { $title = $year; - if ( !empty($monthnum) ) - $title .= " $sep " . $wp_locale->get_month($monthnum); - if ( !empty($day) ) - $title .= " $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 there is a post - if ( is_single() || is_page() ) { - $post = $wp_query->get_queried_object(); - $title = strip_tags( apply_filters( 'single_post_title', $post->post_title ) ); + // 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' ); } $prefix = ''; - if ( !empty($title) ) + if ( ! empty( $title ) ) { $prefix = " $sep "; + } - // Determines position of the separator - if ( 'right' == $seplocation ) - $title = $title . $prefix; - else - $title = $prefix . $title; + /** + * Filters 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 = array_reverse( $title_array ); + $title = implode( " $sep ", $title_array ) . $prefix; + } else { + $title = $prefix . implode( " $sep ", $title_array ); + } - $title = apply_filters('wp_title', $title, $sep); + /** + * Filters 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 ) + if ( $display ) { echo $title; - else + } else { return $title; + } +} +/** + * Display or retrieve page title for post. + * + * This is optimized for single.php template file for displaying the post 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. + * + * @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|void Title when retrieving. + */ +function single_post_title( $prefix = '', $display = true ) { + $_post = get_queried_object(); + + if ( !isset($_post->post_title) ) + return; + + /** + * Filters 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; -function single_post_title($prefix = '', $display = true) { - global $wpdb; - $p = get_query_var('p'); - $name = get_query_var('name'); + $post_type = get_query_var( 'post_type' ); + if ( is_array( $post_type ) ) + $post_type = reset( $post_type ); - 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); - } + $post_type_obj = get_post_type_object( $post_type ); + + /** + * Filters 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; } +/** + * Display or retrieve page title for category archive. + * + * 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|void Title when retrieving. + */ +function single_cat_title( $prefix = '', $display = true ) { + return single_term_title( $prefix, $display ); +} -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); - } +/** + * Display or retrieve page title for tag post archive. + * + * 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|void Title when retrieving. + */ +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. + * 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(); -function single_tag_title($prefix = '', $display = true ) { - if ( !is_tag() ) + 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() ) { + /** + * Filters 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() ) { + /** + * Filters 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() ) { + /** + * Filters 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; +} +/** + * 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. 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 + * + * @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; @@ -335,276 +1426,550 @@ 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(); -/* link navigation hack by Orien http://icecode.com/ */ + 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' ); + } + + /** + * Filters 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() { + /** + * Filters 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. + * + * The format can be one of four styles. The 'link' for head element, 'option' + * for use in the select element, 'html' for use in list (either ol or ul HTML + * elements). Custom content is also supported using the before and after + * parameters. + * + * 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. + * + * The 'option' format uses the option HTML element for use in select element. + * The value is the url parameter and the before and after parameters are used + * between the text description. + * + * The 'html' format, which is the default, uses the li HTML element for use in + * the list HTML elements. The before parameter is before the link and the after + * parameter is after the closing link. + * + * The custom format uses the before parameter before the link ('a' HTML + * element) and the after parameter after the closing link tag. If the above + * three values for the format are not used, then custom format is assumed. + * + * @since 1.0.0 + * + * @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. Content to prepend to the description. Default empty. + * @param string $after Optional. Content to append to the description. Default empty. + * @return string HTML link content for archive. + */ function get_archives_link($url, $text, $format = 'html', $before = '', $after = '') { $text = wptexturize($text); - $title_text = attribute_escape($text); - $url = clean_url($url); + $url = esc_url($url); if ('link' == $format) - return "\t\n"; + $link_html = "\t\n"; elseif ('option' == $format) - return "\t\n"; + $link_html = "\t\n"; elseif ('html' == $format) - return "\t
  • $before$text$after
    • \n"; + $link_html = "\t
  • $before$text$after
    • \n"; else // custom - return "\t$before$text$after\n"; + $link_html = "\t$before$text$after\n"; + + /** + * Filters the archive link content. + * + * @since 2.6.0 + * @since 4.5.0 Added the `$url`, `$text`, `$format`, `$before`, and `$after` parameters. + * + * @param string $link_html The archive HTML link content. + * @param string $url URL to archive. + * @param string $text Archive text description. + * @param string $format Link format. Can be 'link', 'option', 'html', or custom. + * @param string $before Content to prepend to the description. + * @param string $after Content to append to the description. + */ + return apply_filters( 'get_archives_link', $link_html, $url, $text, $format, $before, $after ); } - -function wp_get_archives($args = '') { +/** + * Display archive links based on type and format. + * + * @since 1.2.0 + * @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' (`